read.pudn.comread.pudn.com/downloads178/ebook/827709/tech... · Nucleus PLUS Internals Manual Software Version 2.1 Part Number 0001027-001 December 15, 2006 Document Revision 301

Nucleus PLUS Internals Manual

Software Version 2.1

Part Number 0001027-001

December 15, 2006

Document Revision 301

© 2006 Mentor Graphics CorporationAll rights reserved.

This document contains information that is proprietary to Mentor Graphics Corporation. The original recipient of thisdocument may duplicate this document in whole or in part for internal business purposes only, provided that this entirenotice appears in all copies. In duplicating any part of this document, the recipient agrees to make every reasonableeffort to prevent the unauthorized use and distribution of the proprietary information.

This document is for information and instruction purposes. Mentor Graphics reserves the right to makechanges in specifications and other information contained in this publication without prior notice, and thereader should, in all cases, consult Mentor Graphics to determine whether any changes have beenmade.

The terms and conditions governing the sale and licensing of Mentor Graphics products are set forth inwritten agreements between Mentor Graphics and its customers. No representation or other affirmationof fact contained in this publication shall be deemed to be a warranty or give rise to any liability of MentorGraphics whatsoever.

MENTOR GRAPHICS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIALINCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY ANDFITNESS FOR A PARTICULAR PURPOSE.

MENTOR GRAPHICS SHALL NOT BE LIABLE FOR ANY INCIDENTAL, INDIRECT, SPECIAL, ORCONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING BUT NOT LIMITED TO LOST PROFITS)ARISING OUT OF OR RELATED TO THIS PUBLICATION OR THE INFORMATION CONTAINED IN IT,EVEN IF MENTOR GRAPHICS CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OFSUCH DAMAGES.

RESTRICTED RIGHTS LEGEND 03/97

U.S. Government Restricted Rights. The SOFTWARE and documentation have been developed entirelyat private expense and are commercial computer software provided with restricted rights. Use,duplication or disclosure by the U.S. Government or a U.S. Government subcontractor is subject to therestrictions set forth in the license agreement provided with the software pursuant to DFARS 227.7202-3(a) or as set forth in subparagraph (c)(1) and (2) of the Commercial Computer Software - RestrictedRights clause at FAR 52.227-19, as applicable.

Contractor/manufacturer is:Mentor Graphics Corporation

8005 S.W. Boeckman Road, Wilsonville, Oregon 97070-7777.Telephone: 503.685.7000

Toll-Free Telephone: 800.592.2210Website: www.mentor.com

SupportNet: www.mentor.com/supportnetSend Feedback on Documentation: www.mentor.com/supportnet/documentation/reply_form.cfm

TRADEMARKS: The trademarks, logos and service marks ("Marks") used herein are the property ofMentor Graphics Corporation or other third parties. No one is permitted to use these Marks without theprior written consent of Mentor Graphics or the respective third-party owner. The use herein of a third-party Mark is not an attempt to indicate Mentor Graphics as a source of a product, but is intended toindicate a product from, or associated with, a particular third party. A current list of Mentor Graphics’trademarks may be viewed at: www.mentor.com/terms_conditions/trademarks.cfm.

http://www.mentor.com

http://www.mentor.com/supportnet

http://www.mentor.com/supportnet/documentation/reply_form.cfm

http://www.mentor.com/terms_conditions/trademarks.cfm

Nucleus PLUS Internals Manual, Software Version 2.1 3December 15, 2006

Table of Contents

Chapter 1Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Purpose of Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19About Nucleus PLUS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Nucleus PLUS Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 2Implementation Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Component Composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Prologue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22After the Prologue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Remainder of File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Component Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Component Descriptive Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25#define Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Structure Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Typedef Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Structure Member Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Global Variable Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Local Variable Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Function Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 3Software Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Operation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Application Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30System Memory Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Service Call Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Error Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32No Error Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Conditional Compilation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Library Specific Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Environment Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Nucleus PLUS Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Table of Contents

4December 15, 2006

Nucleus PLUS Internals Manual, Software Version 2.1

Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 4Component Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Common Services Component (CS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Common Services Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Common Services Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Common Services Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42CSC_Place_On_List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43CSC_Priority_Place_On_List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44CSC_Remove_From_List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Initialization Component (IN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Initialization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46INC_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47OS_Init_Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48INCT_Sys_Mem_Pools_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Nucleus Middleware Initialization Component (NMI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Nucleus Middleware Initialization Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49How to Add New MW Products to the NMI Product Registry Array . . . . . . . . . . . . . . . . 50Nucleus Middleware Initialization Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Product Registration Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Product Registry Array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Product Registry Array Entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Registered Products Data List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Registered Product Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Nucleus Middleware Initialization Function and Callback Typedefs. . . . . . . . . . . . . . . . . 53NMI_REG_FUNC_PTR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54NMI_INIT_CB_PTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55NMI_CLEANUP_CB_PTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Nucleus Middleware Initialization Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56NMI_SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Nucleus Middleware Initialization Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57NMI_Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58NMI_MW_Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59NMI_MW_Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60NMI_Init_Status_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61NMI_Init_Status_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62NMI_Wait_For_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63NMI_Cleanup_Invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64NMI_Product_Data_Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65NMIE_Init_Status_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66NMIE_Init_Status_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67NMIE_Wait_For_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68NMIE_Cleanup_Invoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Thread Control Component (TC). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Thread Control Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Thread Control Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Table of Contents


Created Tasks List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Created Task List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Priority List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Priority Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Sub-Priority Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Lowest Bit Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Execute Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Highest Priority Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Highest Priority HISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Created HISRs List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Total HISRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Active HISR Heads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Active HISR Tails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Execute HISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Current Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78System Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78LISR Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78HISR Protect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Unhandled Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Unhandled Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Initialization Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Task Control Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79HISR Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Protection Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Thread Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84TCCT_Create_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85TCC_Delete_Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86TCCT_Create_HISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87TCC_Delete_HISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88TCCT_Reset_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89TCC_Terminate_Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90TCC_Resume_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91TCC_Resume_Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92TCC_Suspend_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93TCC_Suspend_Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94TCC_Task_Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95TCC_Task_Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96TCC_Relinquish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97TCC_Time_Slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98TCC_Current_Task_Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99TCC_Current_HISR_Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100TCC_Task_Shell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101TCC_Signal_Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102TCC_Unhandled_Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103TCC_Unhandled_Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104TCCT_Register_LISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105TCCE_Create_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106TCCE_Create_HISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107TCCE_Delete_HISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Table of Contents

6December 15, 2006


TCCE_Delete_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109TCCE_Reset_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110TCCE_Terminate_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111TCCE_Resume_Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112TCCE_Suspend_Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113TCCE_Relinquish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114TCCE_Task_Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115TCCE_Suspend_Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116TCCE_Register_LISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117TCCE_Activate_HISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118TCCE_Validate_Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119TCF_Established_Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120TCF_Established_HISRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121TCF_Task_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122TCF_HISR_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123TCF_Task_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124TCF_HISR_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125TCIT_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126TCS_Change_Priority. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127TCS_Change_Preemption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128TCS_Change_Time_Slice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129TCS_Control_Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130TCS_Receive_Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131TCS_Register_Signal_Handler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132TCST_Send_Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133TCSE_Change_Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134TCSE_Change_Preemption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135TCSE_Change_Time_Slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136TCSE_Control_Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137TCSE_Receive_Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138TCSE_Register_Signal_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139TCSE_Send_Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140TCCT_Control_Interrupts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141TCCT_Check_Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142TCCT_Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143TCCT_Control_To_System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144TCCT_Signal_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145TCCT_Current_Thread. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146TCCT_Set_Execute_Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147TCCT_Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148TCCT_Unprotect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149TCCT_Unprotect_Specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150TCCT_Set_Current_Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151TCCT_Get_Current_Protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152TCCT_Protect_Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153TCCT_Dispatch_LISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154TCCT_Dispatch_Nested_LISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155TCCT_Activate_HISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156TCCT_HISR_Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Table of Contents


Timer Component (TM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Timer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Timer Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Created Timers List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Created Timer List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Total Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Active Timers List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Active List Busy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160System Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Timer Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Timer State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Time-slice Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161HISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161HISR Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Timer Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Application Timer Control Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Timer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163TMC_Init_Task_Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164TMC_Start_Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165TMC_Stop_Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166TMC_Timer_HISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167TMC_Timer_Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168TMF_Established_Timers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169TMF_Get_Remaining_Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170TMF_Timer_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171TMF_Timer_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172TMIT_Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173TMS_Create_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174TMS_Delete_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175TMS_Reset_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176TMS_Control_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177TMSE_Create_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178TMSE_Delete_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179TMSE_Reset_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180TMSE_Control_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181TMCT_Set_Clock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182TMCT_Retrieve_Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183TMCT_Increment_Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184TMCT_Read_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185TMCT_Enable_Timer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186TMCT_Adjust_Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187TMCT_Retrieve_TS_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188TMCT_Timer_Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Mailbox Component (MB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Mailbox Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Mailbox Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Created Mailbox List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Created Mailbox List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Table of Contents

8December 15, 2006


Total Mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Mailbox Control Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Mailbox Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Mailbox Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194MBC_Create_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195MBC_Delete_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196MBC_Send_To_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197MBC_Receive_From_Mailbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198MBC_Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199MBCE_Create_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200MBCE_Delete_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201MBCE_Send_To_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202MBCE_Receive_From_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203MBF_Established_Mailboxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204MBF_Mailbox_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205MBF_Mailbox_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206MBS_Reset_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207MBS_Broadcast_To_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208MBSE_Reset_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209MBSE_Broadcast_To_Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Queue Component (QU) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Queue Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Queue Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Created Queue List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Created Queue List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Total Queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Queue Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Queue Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Queue Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215QUC_Create_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216QUC_Delete_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217QUC_Send_To_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218QUC_Receive_From_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219QUC_Cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220QUCE_Create_Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221QUCE_Delete_Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222QUCE_Send_To_Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223QUCE_Receive_From_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224QUF_Established_Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225QUF_Queue_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226QUF_Queue_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227QUS_Reset_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228QUS_Send_To_Front_Of_Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229QUS_Broadcast_To_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230QUSE_Reset_Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231QUSE_Send_To_Front_Of_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232QUSE_Broadcast_To_Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Pipe Component (PI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Pipe Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Table of Contents


Pipe Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Created Pipe List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Created Pipe List Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Total Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Pipe Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Pipe Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238PIC_Create_Pipe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239PIC_Delete_Pipe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240PIC_Send_To_Pipe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241PIC_Receive_From_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242PIC_Cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243PICE_Create_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244PICE_Delete_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245PICE_Send_To_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246PICE_Receive_From_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247PIF_Established_Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248PIF_Pipe_Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249PIF_Pipe_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250PIS_Reset_Pipe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251PIS_Send_To_Front_Of_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252PIS_Broadcast_To_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253PISE_Reset_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254PISE_Send_To_Front_Of_Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255PISE_Broadcast_To_Pipe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Semaphore Component (SM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Semaphore Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Semaphore Data Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Created Semaphore List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Created Semaphore List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Total Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Semaphore Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Semaphore Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Semaphore Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261SMC_Create_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262SMC_Delete_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263SMC_Obtain_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264SMC_Release_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265SMC_Cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266SMCE_Create_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267SMCE_Delete_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268SMCE_Obtain_Semaphore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269SMCE_Release_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270SMF_Established_Semaphores. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271SMF_Semaphore_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272SMF_Semaphore_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273SMS_Reset_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274SMSE_Reset_Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Event Group Component (EV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Event Group Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Table of Contents

10December 15, 2006


Event Group Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Created Event Group List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Created Event Group List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Total Event Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Event Group Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Event Group Suspension Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Event Group Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279EVC_Create_Event_Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280EVC_Delete_Event_Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281EVC_Set_Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282EVC_Retrieve_Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283EVC_Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284EVCE_Create_Event_Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285EVCE_Delete_Event_Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286EVCE_Set_Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287EVCE_Retrieve_Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288EVF_Established_Event_Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289EVF_Event_Group_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290EVF_Event_Group_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Partition Memory Component (PM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Partition Memory Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Partition Memory Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Created Partition Memory List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Created Partition Memory List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Total Partition Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Available Partitions List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Partition Pool Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Partition Memory Pool Header Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Partition Memory Pool Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Partition Memory Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297PMC_Create_Partition_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298PMC_Delete_Partition_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299PMC_Allocate_Partition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300PMC_Deallocate_Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301PMC_Cleanup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302PMCE_Create_Partition_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303PMCE_Delete_Partition_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304PMCE_Allocate_Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305PMCE_Deallocate_Partition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306PMF_Established_Partition_Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307PMF_Partition_Pool_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308PMF_Partition_Pool_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Dynamic Memory Component (DM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Dynamic Memory Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Dynamic Memory Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Created Dynamic Memory List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Created Dynamic Memory List Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Total Dynamic Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Available Memory List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Table of Contents


Dynamic Pool Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Dynamic Memory Pool Header Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Dynamic Memory Pool Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Dynamic Memory Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316DMC_Create_Memory_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317DMC_Delete_Memory_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318DMC_Allocate_Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319DMC_Deallocate_Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320DMC_Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321DMCE_Create_Memory_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322DMCE_Delete_Memory_Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323DMS_Allocate_Aligned_Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324DMCE_Allocate_Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325DMCE_Deallocate_Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326DMF_Established_Memory_Pools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327DMF_Memory_Pool_Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328DMF_Memory_Pool_Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Zero Copy Component (ZC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Zero Copy Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Zero Copy Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Object Identification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332ZC_GLOBAL_DATA OBJECT TYPE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332ZC_AVAILABLE OBJECT TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333ZC_BUFFER OBJECT TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333ZC_SEGMENT OBJECT TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334ZC_DATA OBJECT TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Data Access within the ZC Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

ZC Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337ZC_Seg_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338ZC_Seg_Chain_Insert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339ZC_Seg_Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340ZC_Seg_Data_Remove. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341ZC_Seg_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342ZC_Data_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343ZC_Data_Ref_Remove. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344ZC_Obj_Allocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345ZC_Obj_Deallocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346ZC_Mem_Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347ZC_Buf_Seg_Error_Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Input/Output Driver Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Input/Output Driver FilesInput/Output Driver Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Input/Output Data StructuresInput/Output Data Structures . . . . . . . . . . . . . . . . . . . . . . . . 349

Created Input/Output List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Input/Output Driver Control Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Created Input/Output List Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Total Input/Output Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Input/Output Driver Request Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Input/Output Driver Initialization Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Input/Output Driver Assignment Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Table of Contents

12December 15, 2006


Input/Output Driver Release Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Input/Output Driver Input Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Input/Output Driver Output Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Input/Output Driver Status Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Input/Output Driver Terminate Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Input/Output Driver FunctionsInput/Output Driver Functions. . . . . . . . . . . . . . . . . . . . . . 356IOC_Create_Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357IOC_Delete_Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358IOC_Request_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359IOC_Resume_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360IOC_Suspend_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361IOCE_Create_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362IOCE_Delete_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363IOCE_Request_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364IOCE_Resume_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365IOCE_Suspend_Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366IOF_Established_Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367IOF_Driver_Pointers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

History Component (HI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369History Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369History Data Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

History Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Write Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Read Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370History Table Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370Total Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370History Table Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

History Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371HIC_Disable_History_Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372HIC_Enable_History_Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373HIC_Make_History_Entry_Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374HIC_Make_History_Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375HIC_Retrieve_History_Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Error Component (ER). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Error Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Error Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Error Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378ERC_System_Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379ERC_Assert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380Error MacrosError Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381NU_ASSERTERC_System_Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382NU_CHECKERC_System_Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Release Component (RL). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Release Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Release Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Release Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Release Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384RLC_Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Table of Contents


RLC_Get_Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Release Macros Error Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387PLUS_RELEASE_STRING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Chapter 5ESAL Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389ESAL File Naming Convention. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392Component Functional Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Generic Component (GE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

Generic Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397Generic Component Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

OS Entry Point for Interrupt Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398OS Entry Point for Nested Interrupt Service Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . 398Interrupt Handlers and Interrupt Vector IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398Interrupt Service Routine is Executing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Exception Handlers and Exception Vector IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Memory Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401System Stack Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Pointer to the Start of the System Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Exception Stack Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401Pointer to the Start of the Exception Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402OS Entry Point for Unsolicited Execution Thread Switching . . . . . . . . . . . . . . . . . . . . . 402Unsolicited Execution Thread Switch Is Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Generic Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402ESAL_GE_DBG_Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403ESAL_GE_DBG_Default_Brk_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404ESAL_GE_INT_All_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405ESAL_GE_INT_Global_Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406ESAL_GE_INT_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407ESAL_GE_INT_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408ESAL_GE_ISR_Default_Exc_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409ESAL_GE_ISR_Default_Int_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410ESAL_GE_ISR_Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411ESAL_GE_ISR_OS_Default_Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412ESAL_GE_ISR_OS_RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413ESAL_GE_MEM_Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414ESAL_GE_MEM_Copy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415ESAL_GE_MEM_Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416ESAL_GE_MEM_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417ESAL_GE_MEM_CACHE_ALL_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418ESAL_GE_MEM_CACHE_ALL_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419ESAL_GE_MEM_DCACHE_ALL_INVALIDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420ESAL_GE_MEM_ICACHE_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421ESAL_GE_MEM_DCACHE_INVALIDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422ESAL_GE_MEM_DCACHE_ALL_FLUSH_INVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 423ESAL_GE_MEM_DCACHE_FLUSH_INVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Table of Contents

14December 15, 2006


ESAL_GE_MEM_Next_Match_Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425ESAL_GE_MEM_Region_Addr_Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426ESAL_GE_MEM_Remaining_Size_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427ESAL_GE_RTE_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428ESAL_GE_STK_Except_Stack_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429ESAL_GE_STK_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430ESAL_GE_STK_System_SP_End_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431ESAL_GE_STK_System_SP_Start_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432ESAL_GE_STK_Unsol_Switch_Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433ESAL_GE_TMR_OS_ISR_Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434ESAL_GE_TMR_OS_Timer_Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Toolset Specific Component (TS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Toolset Specific Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436Toolset Specific Component Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Toolset Stack Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Toolset Specific Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437ESAL_TS_MEM_BSS_Clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438ESAL_TS_MEM_First_Avail_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439ESAL_TS_MEM_ROM_To_RAM_Copy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440ESAL_TS_RTE_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441ESAL_TS_RTE_Lowlevel_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442ESAL_TS_STK_Solicited_Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443ESAL_TS_STK_Solicited_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444ESAL_TS_STK_Solicited_Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Architecture Specific Component (AR). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Architecture Specific Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446Architecture Specific Data Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

Architecture Interrupt Control Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Architecture Vector Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Minimum Architecture Stack Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Architecture Stack Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

Architecture Specific Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448ESAL_AR_DBG_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449ESAL_AR_DBG_Reg_Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450ESAL_AR_DBG_Reg_Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451ESAL_AR_DBG_Opcode_Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452ESAL_AR_DBG_Opcode_Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453ESAL_AR_DBG_Opcode_Brk_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454ESAL_AR_DBG_Step_Addr_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455ESAL_AR_DBG_Condition_Met . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456ESAL_AR_DBG_Reg_Shifted_Get. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457ESAL_AR_DBG_Brk_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458ESAL_AR_DBG_Brk_Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459ESAL_AR_INT_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460ESAL_AR_INT_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461ESAL_AR_ISR_<Exception_Type>_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462ESAL_AR_ISR_<Interrupt_Type>_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463ESAL_AR_ISR_Initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465ESAL_AR_ISR_Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Table of Contents


ESAL_AR_ISR_Vector_Table_Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467ESAL_AR_STK_SP_GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468ESAL_AR_STK_SP_SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469ESAL_AR_STK_Startup_SP_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470ESAL_AR_STK_Unsolicited_Restore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471ESAL_AR_STK_Unsolicited_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472ESAL_AR_TMR_OS_Timer_Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

Core Specific Component (CO). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Core Specific Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Core Specific Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474ESAL_CO_MEM_Cache_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475ESAL_CO_MEM_CACHE_ALL_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476ESAL_CO_MEM_ICACHE_ALL_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477ESAL_CO_MEM_DCACHE_ALL_INVALIDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478ESAL_CO_MEM_ICACHE_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479ESAL_CO_MEM_DCACHE_INVALIDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480ESAL_CO_MEM_DCACHE_ALL_FLUSH_INVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 481ESAL_CO_MEM_DCACHE_FLUSH_INVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

Processor Specific Component (PR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Processor Specific Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483Processor Specific Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483ESAL_PR_INT_All_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484ESAL_PR_INT_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485ESAL_PR_INT_Disable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486ESAL_PR_ISR_<Interrupt_Type>_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487ESAL_PR_ISR_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488ESAL_PR_MEM_Cache_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489ESAL_PR_MEM_CACHE_ALL_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490ESAL_PR_MEM_ICACHE_ALL_INVALIDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491ESAL_PR_MEM_DCACHE_ALL_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492ESAL_PR_MEM_ICACHE_INVALIDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493ESAL_PR_MEM_DCACHE_INVALIDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494ESAL_PR_MEM_DCACHE_ALL_FLUSH_INVAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . 495ESAL_PR_MEM_DCACHE_FLUSH_INVAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496ESAL_PR_MEM_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497ESAL_PR_TMR_OS_Timer_Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

Development Platform Specific Component (DP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Development Platform Specific Component Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Development Platform Specific Component Data Structures . . . . . . . . . . . . . . . . . . . . . . 500

System Memory Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500Number of System Memory Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500Development Platform Specific Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 500

ESAL_Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501ESAL_DP_INT_All_Disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502ESAL_DP_INT_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503ESAL_DP_INT_Disable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504ESAL_DP_ISR_<Interrupt_Type>_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505ESAL_DP_ISR_Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

Summary Flow Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

Table of Contents

16December 15, 2006


End-User License Agreement


List of Figures

Figure 4-1. NMI Product Data List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Figure 4-2. TCD Created Tasks List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Figure 4-3. TCD Priority List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Figure 4-4. TCD Priority Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Figure 4-5. TCD Sub-Priority Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Figure 4-6. TCD Lowest Set Bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Figure 4-7. TCD Created HISRs List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Figure 4-8. TCD Active HISRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Figure 4-9. TMD Created Timers List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Figure 4-10. TMD Active Timers List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Figure 4-11. MBD Created Mailboxes List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Figure 4-12. Mailbox Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Figure 4-13. QUD Created Queues List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Figure 4-14. Queue Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Figure 4-15. PID Created Pipes List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Figure 4-16. Pipe Suspension Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Figure 4-17. SMD Created Semaphores List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258Figure 4-18. Semaphore Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Figure 4-19. EVD Created Events Group List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Figure 4-20. Event Group Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Figure 4-21. PMD Created Pools List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Figure 4-22. Available Partitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Figure 4-23. Partition Memory Pool Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . . 296Figure 4-24. DMD Created Pools List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Figure 4-25. Available Memory List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Figure 4-26. Dynamic Memory Pool Suspension Structure . . . . . . . . . . . . . . . . . . . . . . . . . 315Figure 4-27. Object Types and Usages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Figure 4-28. ZC Object Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Figure 4-29. IOD Created Drivers List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Figure 5-1. ESAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389Figure 5-2. ESAL Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392Figure 5-3. Abstract View of ESAL Hardware Components . . . . . . . . . . . . . . . . . . . . . . . . 393Figure 5-4. Example of ESAL Hardware Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394Figure 5-5. ESAL Component Functional Areas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Figure 5-6. ESAL_GE_ISR_Interrupt_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399Figure 5-7. ESAL_GE_ISR_Exception_Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Figure 5-8. ESAL Initialization (Reset) Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507Figure 5-9. ESAL Low-Level Interrupt Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

18December 15, 2006



Chapter 1Introduction

Purpose of ManualThis manual contains information on Nucleus PLUS real-time kernel. It documents the internalstructure and interfaces of Nucleus PLUS. It describes how the software works, and alsoprovides guidelines on how to extend or modify this software to meet special needs.

Nucleus PLUS is delivered in source code form. Since the source code for Nucleus PLUS isfairly large, a typical user may find it difficult to understand all the components, structures, anddata. This manual is designed to help Nucleus PLUS users understand the source code.

About Nucleus PLUSNucleus PLUS is a real-time, preemptive, multitasking kernel designed for time-criticalembedded applications. Nucleus PLUS library is written in ANSI C. Because of this, NucleusPLUS is extremely portable and is currently available for use with most microprocessorfamilies.

Nucleus PLUS is typically implemented as a C library. Real-time Nucleus PLUS applicationsare linked with the Nucleus PLUS library. The resulting object may be downloaded to thetarget or placed in ROM.

Nucleus PLUS ConstructionMentor Graphics software development practices facilitate clarity, modularity, reliability,reusability, and ease of maintenance. Nucleus PLUS is comprised of multiple softwarecomponents. Each software component has a unique purpose and a specific external interfaceto other components. The composition of each Nucleus PLUS software component is discussedin greater detail in subsequent chapters.


IntroductionNucleus PLUS Construction

December 15, 2006


Chapter 2Implementation Conventions

ComponentsMentor Graphics uses a software component methodology. A software component has a single,clear purpose. Software components are typically comprised of several C files. Each softwarecomponent provides a well-defined external interface. Utilization of a component isaccomplished through use of its external interface. With few exceptions, access to global datastructures within a component is not allowed outside of the component. Because of thiscomponent methodology, Nucleus PLUS software components are both easy to replace andeasy to re-use.

Component CompositionA software component is typically comprised of an include file for data type definitions andconstants, an include file for the component’s external interfaces, and one or more C and/orassembly files. Component filenames conform to the following conventions:

Table 2-1. Component Filenaming Conventions

File Meaning

xx_defs.h Component constants and data structures aredefined in this file.

xx_extr.h External interfaces to the component are defined inthis file. These interfaces are defined in terms offunction prototypes.

xxd.c Static and global data structures within thecomponent are defined in this file. With fewexceptions, data structures of one component areonly accessed from functions within thecomponent.

xxi_<descriptive_name>.c The component initialization functions are definedin these files.

xxit_<descriptive_name>.c The component target dependent initializationfunctions are defined in these files.

xxf_<descriptive_name>.c This file contains functions that provide statusinformation about objects managed by thecomponent.


Implementation ConventionsComponent Composition

December 15, 2006

NoteThe xx represents the two-letter name of the component. The <descriptive_name>represents the descriptive word used for each .c file. A component does not necessarilyhave every possible type of file. For more information concerning descriptive namesrefer to the “Component Descriptive Names” section.

FormatAll software source files have the same fundamental format. The first part of the file containsgeneral information about the file and is called the prologue. The second part of the file isdedicated to internal data declarations and internal function prototyping. The remaining part ofthe file contains the actual functions.

PrologueThe purpose of the prologue is to describe the contents of the file, identify Mentor GraphicsCorporation as the owner of the file, and to provide information about revisions to the file.

An example of the prologue format follows:

/******************************************************************** Copyright Mentor Graphics Corporation 200x* All Rights Reserved.** THIS WORK CONTAINS TRADE SECRET AND PROPRIETARY INFORMATION

xxfe_<descriptive_name>.c These files contain the error-checking shellfunctions for status information functions.

xxc_<descriptive_name>.c This file contains the core functions of thecomponent.

xxce_<descriptive_name>.c These files contain the error-checking shellfunctions for the core functions.

xxct_<descriptive_name>.c These files contain the core target dependentfunctions of the component.

xxs_<descriptive_name>.c Supplemental functions for the component aredefined in these files.

xxse_<descriptive_name>.c Error-checking functions for the supplementalcomponent functions are defined in these files.

xxst_<descriptive_name>.c Supplemental target dependent functions for thecomponent are defined in these files.

Table 2-1. Component Filenaming Conventions (cont.)

File Meaning

Implementation ConventionsComponent Composition


* WHICH IS THE PROPERTY OF MENTOR GRAPHICS CORPORATION OR ITS* LICENSORS AND IS SUBJECT TO LICENSE TERMS.******************************************************************** FILE NAME** [name of this file]** COMPONENT** [identifies the component]** DESCRIPTION** [general description of this file]** DATA STRUCTURES** [global component data structures defined in this file]** FUNCTIONS** [functions defined in this file]** DEPENDENCIES** [other file dependencies]******************************************************************/

After the PrologueThe area after the prologue is reserved for constants, global data structure definitions, and inter-component function prototypes. Of course, include files only define component data structuretypes or external interfaces.

Remainder of FileThe remainder of a software component file consists of C functions. Each function is precededby a description block. The format of a function description block follows:

/******************************************************************FUNCTION** [name of the function]** DESCRIPTION** [general description of function]** CALLED BY** [functions that call this function]*


Implementation ConventionsNaming Conventions

December 15, 2006

* CALLS** [functions called by this function]** INPUTS** [inputs to the function]** OUTPUTS** [outputs of this function]******************************************************************/

Naming ConventionsNaming conventions are intended to make examination of the Mentor source code less difficultby incorporating the first three or four characters of the filename into global variable andfunction names. Of course, all names correspond to their usage. Detailed descriptions of thenaming conventions are described in the following sub-sections

Component NamesComponent names are generally limited to two characters. The component name is used as thefirst two characters of each file that make up the component.

Example:

Thread Control Component Name: TC

This is a partial list of files that are part of the TC:

tc_defs.h

tc_extr.h

tcc_common.c

tcce_common.c

tcct_common.c

tcd.c

tcf_established.c

tcfe_info.c

tcit_common.c



tcs_preemption.c

tcse_preemption.c

tcst_signal.c

Component Descriptive NamesComponent filenames are chosen to be descriptive of the functions that are contained within thefile. The descriptive names are added to the end of the name of each .c file. One or moredescriptive words may be used, with each word separated by an underscore character.Component functions have been split into separate files based on their component type andrelationships to other functions.

Example:

These are typical descriptive function filenames:

csc_common.c

dmc_common.c

dmc_delete.c

dmf_established.c

tcct_create.c

tcct_interrupts.c

tcct_register.c

tcct_reset_task.c

tcct_signal.c

#define NamesDefines are comprised of underscores, capital letters, and numeric characters. The maximumlength of a define is 48 characters. Additionally, the first three characters of a define are “EX_”where “EX” is the same as the first two letters of the filename where the define is located.

Example (for the ex_defs.h file):

#define EX_MY_CONSTANT10



December 15, 2006

Structure NamesStructure names are comprised of underscores, capital letters, and numeric characters. Themaximum length of a structure name is 48 characters. Additionally, the first three characters ofa structure name are “EX_” where “EX” is the same as the first two letters of the filenamewhere the structure is defined.


struct EX_MY_STRUCT{ INT ex_member_a; INT ex_member_b; INT ex_member_c;};

Typedef NamesTypedef names are comprised of underscores, capital letters, and numeric characters. Themaximum length of a typedef name is 48 characters. Additionally, the first three characters of atypedef name are “EX_” where “EX” is the same as the first two letters of the filename thetypedef is defined in.


typedef struct EX_MY_STRUCT{ INT ex_member_a; INT ex_member_b; INT ex_member_c;} EX_MY_TYPEDEF;

Structure Member NamesStructure member names are comprised of underscores, lowercase letters, andnumeric characters. The maximum length of structure member names is 48 characters.Additionally, the first three characters of a structure member are defined as “EX_” where “EX”is the same as the first two letters of the ex_defs.h file that contains the structure definition.


struct EX_MY_STRUCT{ INT ex_member_a; INT ex_member_b; INT ex_member_c;};



Global Variable NamesNucleus PLUS global variable names are comprised of underscores, a single uppercasecharacter following each underscore, lowercase characters, and numeric characters. Themaximum length of a global variable name is 48 characters. Additionally, the first three lettersof a global variable name are defined as “EXC” where “exc” is the same as the first three lettersof the exc.c file that contains the actual variable declaration.

Example (for the exd.c file):

INT EXD_Global_Integer;

Local Variable NamesLocal variable names (names for variables defined inside the context of a C function) arecomprised of lowercase characters and possibly underscores and/or numeric characters. Themaximum length of a local variable name is 48 characters. Local variable names are notrequired to take the first three characters of the file they are defined in.


/* Assume the following declaration is inside a function. */ INT i;

Function NamesNucleus PLUS function names are comprised of underscores, a single uppercase characterfollowing each underscore, lowercase characters, and numeric characters. The maximum lengthof a function name is 48 characters. Additionally, the first three characters of a function nameare the same as those of the file that contains the function definition.


VOID EXD_My_Function(UNSIGNED i){ . . .}


Implementation ConventionsIndentation

December 15, 2006

IndentationThe basic unit of indentation is four spaces. Function declarations, variable declarations, andconditional compilation constructs start at column one. Actual instructions start at column four.

Notethe braces { and } are on separate lines. The { brace has the same indentation as theprevious line, while the } brace lines up with the previous { brace.


VOID EXD_Example_Function(INT i, INT b){

UNSIGNED a;CHAR b;

/* Actual instructions start. */ i = 0; while (i < 100) { /* Increment i. */ i = i + 1; }

CommentsComments are one of the most important features of the Nucleus PLUS source code. They areused in a meaningful and plentiful manner. There are two principal types of comments inMentor software. The first type of comment starts at the current indentation, while the secondtype of comment starts at column 45.

Example:

/* This is the first type of meaningful comment. */i = 10;j++; /* This is the second type of comment. */


Chapter 3Software Overview

Basic UsageNucleus PLUS is typically implemented as C library. Real-time Nucleus PLUS applications arelinked with the Nucleus PLUS library and the Embedded Software Abstraction Layer (ESAL)libraries. The resulting object may then be downloaded to the target (RAM) or placed in ROM.

Operation ModeIn processor architectures that have both supervisor and user modes of operation, NucleusPLUS application tasks typically run in supervisor mode. This is because application tasksmake direct calls to operating system services that utilize privileged instructions. This methodreduces service call overhead and is also much easier to implement, but it allows the tasks tohave full access to everything. Mentor has products available for more control over modes andtask access.

Application InitializationYou are responsible for providing your own initialization function, which is called Application_Initialize. This function should create the tasks, queues, and other system objects that arerequired when the system starts. If the application does not utilize dynamic creation/ deletion ofsystem objects during run-time, all of the required system objects may be created in Application_Initialize. Multitasking begins immediately after the your Application_Initialize functionreturns.

Table 3-1. Library Names

Library Description

plus.lib This library contains all of the Nucleus PLUScomponents.

esal.lib This library contains all of the EmbeddedSoftware Abstraction (ESAL) functionality(except board).

esal_board.lib This library contains all of the EmbeddedSoftware Abstraction (ESAL) board levelfunctionality.


Software OverviewData Types

December 15, 2006

Include FileAll user code that references Nucleus PLUS services and/or data types must include the filenucleus.h. This file contains data type definitions, constant definitions, and function prototypesfor all of the Nucleus PLUS services.

System Memory PoolsNucleus PLUS creates two dynamic memory pools that can be used by middleware andapplications.

The first memory pool contains cached or uncached memory (depending on availability andconfiguration of cache on the target hardware). The global variable System_Memory is thecontrol block name for this memory pool.

The second memory pool always contains uncached memory. The global variableUncached_System_Memory is the control block name for this memory pool.

If there is no cached memory on the target hardware, the full block of available memory is splitinto two equal sized memory pools of uncached memory (utilizing the same control blocknames stated above).

The size of both of these pools is dependant on the available memory configured on the targethardware (within ESAL). The two pools created will contain the largest blocks of memorygiven these restrictions.

NotePointers to both memory pools are passed to Application_Initialize. The global namesand creation methods for both pools mentioned above may change in future versions ofNucleus PLUS. For this reason, applications should utilize the memory pool pointerspassed to Application_Initialize instead of the global variables (System_Memory andUncached_System_Memory).

Data TypesNucleus PLUS defines several standard data types in the file nucleus.h. These data types areguaranteed to remain constant in capability by assigning the appropriate target C compiler’sbasic data type. Therefore, Nucleus PLUS can perform in an identical manner on a variety oftarget environments.



The following data types are defined by Nucleus PLUS:

Service Call MappingThe main Nucleus PLUS include file, nucleus.h, contains function prototypes that match thosedefined in the Nucleus PLUS Reference Manual. However, the NU_* functions do not reallyexist. For most Nucleus PLUS services, there exists a function that really does the work and a“shell” function that checks for errors in the user’s request before calling the real function.Depending on the error checking configuration setting within plus_cfg.h, NU_ERROR_CHECKING, the Nucleus PLUS service call is mapped, through macro substitution, to theappropriate underlying function. This facilitates complete elimination of error checking when itis not required.

Table 3-2. Data Types

Data Type Meaning

UNSIGNED This is required to be a 32-bit unsignedinteger. It is usually defined as an unsignedlong C data type.

SIGNED This is required to be a 32-bit signed integer.It is usually defined as a signed long C datatype.

DATA_ELEMENT Smallest data type that is easily manipulated- usually an unsigned char C data type.

OPTION Same as the previous DATA_ELEMENTtype.

BOOLEAN Same as the previous DATA_ELEMENTdata type.

STATUS Equivalent to target C compiler’s signed intdata type.

UNSIGNED_CHAR This data type is required to be an 8-bitunsigned character.

CHAR This data type is required to be an 8-bitcharacter.

UNSIGNED_INT This is an unsigned integer data type.

UNSIGNED_PTR This data type is a pointer to an unsigned 32-bit data type.

BYTE_PTR This data type is a pointer to an unsigned 8-bit data type.



December 15, 2006

Error CheckingIf the NU_ERROR_CHECKING flag is defined to NU_TRUE in plus_cfg.h (default condition),the NU_* service calls defined in the Nucleus PLUS Reference Manual are mapped to thefollowing internal functions:

Table 3-3. NU_ERROR_CHECKING = NU_TRUE Default Mappings

Nucleus PLUS Service Internal Function

NU_Activate_HISR TCCE_Activate_HISR

NU_Allocate_Aligned_Memory DMS_Allocate_Aligned_Memory

NU_Allocate_Memory DMCE_Allocate_Memory

NU_Allocate_Partition PMCE_Allocate_Partition

NU_Broadcast_To_Mailbox MBSE_Broadcast_To_Mailbox

NU_Broadcast_To_Pipe PISE_Broadcast_To_Pipe

NU_Broadcast_To_Queue QUSE_Broadcast_To_Queue

NU_Change_Preemption TCSE_Change_Preemption

NU_Change_Priority TCSE_Change_Priority

NU_Change_Time_Slice TCSE_Change_Time_Slice

NU_Check_Stack TCCT_Check_Stack

NU_Control_Interrupts TCCT_Control_Interrupts

NU_Control_Signals TCSE_Control_Signals

NU_Control_Timer TMSE_Control_Timer

NU_Create_Driver IOCE_Create_Driver

NU_Create_Event_Group EVCE_Create_Event_Group

NU_Create_HISR TCCE_Create_HISR

NU_Create_Mailbox MBCE_Create_Mailbox

NU_Create_Memory_Pool DMCE_Create_Memory_Pool

NU_Create_Partition_Pool PMCE_Create_Partition_Pool

NU_Create_Pipe PICE_Create_Pipe

NU_Create_Queue QUCE_Create_Queue

NU_Create_Semaphore SMCE_Create_Semaphore

NU_Create_Task TCCE_Create_Task

NU_Create_Timer TMSE_Create_Timer

NU_Current_HISR_Pointer TCC_Current_HISR_Pointer



NU_Current_Task_Pointer TCC_Current_Task_Pointer

NU_Deallocate_Memory DMCE_Deallocate_Memory

NU_Deallocate_Partition PMCE_Deallocate_Partition

NU_Delete_Driver IOCE_Delete_Driver

NU_Delete_Event_Group EVCE_Delete_Event_Group

NU_Delete_HISR TCCE_Delete_HISR

NU_Delete_Mailbox MBCE_Delete_Mailbox

NU_Delete_Memory_Pool DMCE_Delete_Memory_Pool

NU_Delete_Partition_Pool PMCE_Delete_Partition_Pool

NU_Delete_Pipe PICE_Delete_Pipe

NU_Delete_Queue QUCE_Delete_Queue

NU_Delete_Semaphore SMCE_Delete_Semaphore

NU_Delete_Task TCCE_Delete_Task

NU_Delete_Timer TMSE_Delete_Timer

NU_Disable_History_Saving HIC_Disable_History_Saving

NU_Driver_Pointers IOF_Driver_Pointers

NU_Enasble_History_Saving HIC_Enable_History_Saving

NU_Established_Drivers IOF_Established_Drivers

NU_Established_Event_Groups EVF_Established_Event_Groups



NU_Established_HISRs TCF_Established_HISRs

NU_Established_Mailboxes MBF_Established_Mailboxes

NU_Established_Memory_Pools DMF_Established_Memory_Pools

NU_Established_Partition_Pools PMF_Established_Partition_Pools

NU_Established_Pipes PIF_Established_Pipes

NU_Established_Queues QUF_Established_Queues

NU_Established_Semaphores SMF_Established_Semaphores

NU_Established_Tasks TCF_Established_Tasks

NU_Established_Timers TMF_Established_Timers

Table 3-3. NU_ERROR_CHECKING = NU_TRUE Default Mappings (cont.)




December 15, 2006

NU_Event_Group_Information EVF_Event_Group_Information

NU_Event_Group_Pointers EVF_Event_Group_Pointers

NU_Get_Remaining_Time TMF_Get_Remaining_Time

NU_HISR_Information TCF_HISR_Information

NU_HISR_Pointers TCF_HISR_Pointers

NU_Local_Control_Interrupts ESAL_GE_INT_Global_Set

NU_Mailbox_Information MBF_Mailbox_Information

NU_Mailbox_Pointers MBF_Mailbox_Pointers

NU_Make_History_Entry HIC_Make_History_Entry_Service

NU_Memory_Pool_Information DMF_Memory_Pool_Information

NU_Memory_Pool_Pointers DMF_Memory_Pool_Pointers

NU_NMI_Cleanup_Invoke NMIE_Cleanup_Invoke

NU_NMI_Init_Status_Get NMIE_Init_Status_Get

NU_NMI_Init_Status_Set NMIE_Init_Status_Set

NU_NMI_Wait_For_Init NMIE_Wait_For_Init

NU_Obtain_Semaphore SMCE_Obtain_Semaphore

NU_Partition_Pool_Information PMF_Partition_Pool_Information

NU_Partition_Pool_Pointers PMF_Partition_Pool_Pointers

NU_Pipe_Information PIF_Pipe_Information

NU_Pipe_Pointers PIF_Pipe_Pointers

NU_Protect TCCT_Protect

NU_Queue_Information QUF_Queue_Information

NU_Queue_Pointers QUF_Queue_Pointers

NU_Receive_From_Mailbox MBCE_Receive_From_Mailbox

NU_Receive_From_Pipe PICE_Receive_From_Pipe

NU_Receive_From_Queue QUCE_Receive_From_Queue

NU_Receive_Signals TCSE_Receive_Signals

NU_Register_LISR TCCE_Register_LISR

NU_Register_Signal_Handler TCSE_Register_Signal_Handler

NU_Release_Information RLC_Release_Information





No Error CheckingIf the NU_ERROR_CHECKING flag is defined to NU_FALSE, the NU_* service calls definedin the Nucleus PLUS Reference Manual are mapped to the following internal functions:

NU_Release_Semaphore SMCE_Release_Semaphore

NU_Relinquish TCCE_Relinquish

Table 3-4. NU_ERROR_CHECKING=NU_FALSE Default Mappings


NU_Activate_HISR TCCT_Activate_HISR

NU_Allocate_Aligned_Memory DMS_Allocate_Aligned_Memory

NU_Allocate_Memory DMC_Allocate_Memory

NU_Allocate_Partition PMC_Allocate_Partition

NU_Broadcast_To_Mailbox MBS_Broadcast_To_Mailbox

NU_Broadcast_To_Pipe PIS_Broadcast_To_Pipe

NU_Broadcast_To_Queue QUS_Broadcast_To_Queue

NU_Change_Preemption TCS_Change_Preemption

NU_Change_Priority TCS_Change_Priority

NU_Change_Time_Slice TCS_Change_Time_Slice

NU_Check_Stack TCCT_Check_Stack

NU_Control_Interrupts TCCT_Control_Interrupts

NU_Control_Signals TCS_Control_Signals

NU_Control_Timer TMS_Control_Timer

NU_Create_Driver IOC_Create_Driver

NU_Create_Event_Group EVC_Create_Event_Group

NU_Create_HISR TCCT_Create_HISR

NU_Create_Mailbox MBC_Create_Mailbox

NU_Create_Memory_Pool DMC_Create_Memory_Pool

NU_Create_Partition_Pool PMC_Create_Partition_Pool

NU_Create_Pipe PIC_Create_Pipe

NU_Create_Queue QUC_Create_Queue





December 15, 2006

NU_Create_Semaphore SMC_Create_Semaphore

NU_Create_Task TCCT_Create_Task

NU_Create_Timer TMS_Create_Timer

NU_Current_HISR_Pointer TCF_Current_HISR_Pointer

NU_Current_Task_Pointer TCC_Current_Task_Pointer

NU_Deallocate_Memory DMC_Deallocate_Memory

NU_Deallocate_Partition PMC_Deallocate_Partition

NU_Delete_Driver IOC_Delete_Driver

NU_Delete_Event_Group EVC_Delete_Event_Group

NU_Delete_HISR TCC_Delete_HISR

NU_Delete_Mailbox MBC_Delete_Mailbox

NU_Delete_Memory_Pool DMC_Delete_Memory_Pool

NU_Delete_Partition_Pool PMC_Delete_Partition_Pool

NU_Delete_Pipe PIC_Delete_Pipe

NU_Delete_Queue QUC_Delete_Queue

NU_Delete_Semaphore SMC_Delete_Semaphore

NU_Delete_Task TCC_Delete_Task

NU_Delete_Timer TMS_Delete_Timer

NU_Disable_History_Saving HIC_Disable_History_Saving

NU_Driver_Pointers IOF_Driver_Pointers

NU_Enable_History_Saving HIC_Enable_History_Saving



NU_Established_HISRs TCF_Established_HISRs

NU_Established_Mailboxes MBF_Established_Mailboxes

NU_Established_Memory_Pools DMF_Established_Memory_Pools

NU_Established_Partition_Pools PMF_Established_Partition_Pools

NU_Established_Pipes PIF_Established_Pipes

NU_Established_Queues QUF_Established_Queues

NU_Established_Semaphores SMF_Established_Semaphores

Table 3-4. NU_ERROR_CHECKING=NU_FALSE Default Mappings (cont.)




NU_Established_Tasks TCF_Established_Tasks

NU_Established_Timers TMF_Established_Timers

NU_Event_Group_Information EVF_Event_Group_Information

NU_Event_Group_Pointers EVF_Event_Group_Pointers

NU_Get_Remaining_Time TMF_Get_Remaining_Time

NU_HISR_Information TCF_HISR_Information

NU_HISR_Pointers TCF_HISR_Pointers

NU_Local_Control_Interrupts ESAL_GE_INT_Global_Set

NU_Mailbox_Information MBF_Mailbox_Information

NU_Mailbox_Pointers MBF_Mailbox_Pointers

NU_Make_History_Entry HIC_Make_History_Entry_Service

NU_Memory_Pool_Information DMF_Memory_Pool_Information

NU_Memory_Pool_Pointers DMF_Memory_Pool_Pointers

NU_NMI_Cleanup_Invoke NMI_Cleanup_Invoke

NU_NMI_Init_Status_Get NMI_Init_Status_Get

NU_NMI_Init_Status_Set NMI_Init_Status_Set

NU_NMI_Wait_For_Init NMI_Wait_For_Init

NU_Obtain_Semaphore SMC_Obtain_Semaphore

NU_Partition_Pool_Information PMF_Partition_Pool_Information

NU_Partition_Pool_Pointers PMF_Partition_Pool_Pointers

NU_Pipe_Information PIF_Pipe_Information

NU_Pipe_Pointers PIF_Pipe_Pointers

NU_Protect TCCT_Protect

NU_Queue_Information QUF_Queue_Information

NU_Queue_Pointers QUF_Queue_Pointers

NU_Receive_From_Mailbox MBC_Receive_From_Mailbox

NU_Receive_From_Pipe PIC_Receive_From_Pipe

NU_Receive_From_Queue QUC_Receive_From_Queue

NU_Receive_Signals TCS_Receive_Signals

NU_Register_LISR TCCT_Register_LISR





December 15, 2006

NU_Register_Signal_Handler TCS_Register_Signal_Handler

NU_Release_Information RLC_Release_Information

NU_Release_Semaphore SMC_Release_Semaphore

NU_Relinquish TCC_Relinquish

NU_Request_Driver IOC_Request_Driver

NU_Reset_Mailbox MBS_Reset_Mailbox

NU_Reset_Pipe PIS_Reset_Pipe

NU_Reset_Queue QUS_Reset_Queue

NU_Reset_Semaphore SMS_Reset_Semaphore

NU_Reset_Task TCCT_Reset_Task

NU_Reset_Timer TMS_Reset_Timer

NU_Restore_Interrupts ESAL_GE_INT_Global_Set

NU_Resume_Driver IOC_Resume_Driver

NU_Resume_Task TCC_Resume_Service

NU_Retrieve_Clock TMCT_Retrieve_Clock

NU_Retrieve_Events EVC_Retrieve_Events

NU_Retrieve_History_Entry HIC_Retrieve_History_Entry

NU_Semaphore_Information SMF_Semaphore_Information

NU_Semaphore_Pointers SMF_Semaphore_Pointers

NU_Send_Signals TCST_Send_Signals

NU_Send_To_Front_Of_Pipe PIS_Send_To_Front_Of_Pipe

NU_Send_To_Front_Of_Queue QUS_Send_To_Front_Of_Queue

NU_Send_To_Mailbox MBC_Send_To_Mailbox

NU_Send_To_Pipe PIC_Send_To_Pipe

NU_Send_To_Queue QUC_Send_To_Queue

NU_Set_Clock TMCT_Set_Clock

NU_Set_Events EVC_Set_Events

NU_Sleep TCC_Sleep

NU_Suspend_Driver IOC_Suspend_Driver

NU_Suspend_Task TCC_Suspend_Service





NU_Task_Information TCF_Task_Information

NU_Task_Pointers TCF_Task_Pointers

NU_Terminate_Task TCC_Terminate_Task

NU_Timer_Information TMF_Timer_Information

NU_Timer_Pointers TMF_Timer_Pointers

NU_Unprotect TCCT_Unprotect

NU_ZC_Buf_Create ZC_Buf_Create

NU_ZC_Buf_Delete ZC_Buf_Delete

NU_ZC_Buf_Duplicate ZC_Buf_Duplicate

NU_ZC_Buf_Insert ZC_Buf_Insert

NU_ZC_Buf_Len_Get ZC_Buf_Len_Get

NU_ZC_Buf_Split ZC_Buf_Split

NU_ZC_Data_Copy_Get ZC_Data_Copy_Get

NU_ZC_Data_Copy_Insert ZC_Data_Copy_Insert

NU_ZC_Data_Insert ZC_Data_Insert

NU_ZC_Data_Remove ZC_Data_Remove

NU_ZC_Initialize ZC_Initialize

NU_ZC_Seg_Data_Get ZC_Seg_Data_Get

NU_ZC_Seg_Len_Get ZC_Seg_Len_Get

NU_ZC_Seg_Next_Get ZC_Seg_Next_Get

NU_ZC_Seg_Optimal_Get ZC_Seg_Optimal_Get

NU_ZC_Seg_Prev_Get ZC_Seg_Prev_Get




Software OverviewEnvironment Dependencies

December 15, 2006

Conditional CompilationThe Nucleus PLUS source code has a limited number of conditional compilation options.These options can be configured in the file plus_cfg.h found in the plus directory. There areseveral options available during compilation of application code. However, most options areapplicable to the creation of the Nucleus PLUS library.

Refer to chapter 2 of the Nucleus PLUS Reference Manual for a full explanation of allconditional compilation options.

Library Specific ValuesAll of the defines in Nucleus PLUS are generic. Any values that are library specific areultimately defined in the ESAL library.

Environment DependenciesProcessor and development tool dependencies in Nucleus PLUS have been isolated to the ESALlibrary. The ESAL library contains several generic APIs that are called by Nucleus PLUS. TheESAL library provides the low-level, run-time environment for the underlying targetenvironment.

Nucleus PLUS Include FileThe nucleus.h include file is included by all Nucleus PLUS source files either directly orindirectly. Application files that reference Nucleus PLUS services and/or data types must alsoinclude nucleus.h. This file defines a variety of information such as the common Nucleus PLUSAPI. In addition, it includes other important files that define data types, interrupt lockout/enable values, the number of interrupt vectors, the size of system control blocks, and othertarget specific information.

Version ControlThere are several different version layers in a Nucleus PLUS system. The system version isdefined by three integer values in the file nucleus.h. NU_PLUS_RELEASE_MAJOR_VERSION, NU_PLUS_RELEASE_MINOR_VERSION, and NU_PLUS_RELEASE_PATCH_VERSION. These defines indicate the current version of the generic C source code.


Chapter 4Component Descriptions

This chapter describes various software components of the Nucleus PLUS system. Eachcomponent’s files, data structures, and functions are described.

Common Services Component (CS)The Common Services component (CS) is responsible for providing other Nucleus PLUScomponents with linked list facilities. Each CS node data structure is included within othersystem data structures.

Common Services FilesThe CS consists of three files. Each source file of the CS Component is defined in the followingtable.

Common Services Control BlockThe CS Control Block CS_NODE contains the previous and next pointers to link the CS nodestogether, and other fields necessary for processing CS requests.

Field Declarations

struct CS_NODE_STRUCT *cs_previousstruct CS_NODE_STRUCT *cs_nextDATA_ELEMENT cs_priorityDATA_ELEMENT cs_padding[PAD_1]

Table 4-1. Common Services Component Files

File Description

cs_defs.h This file contains constants and data structure definitions specific to theCS.

cs_extr.h All external interfaces to the CS are defined in this file.

csc_common.c This file contains all of the core functions of the CS. Functions thathandle basic place-on-list and remove-from-list services are defined inthis file. These functions are commonly used collectively.


Component DescriptionsCommon Services Component (CS)

December 15, 2006

Field Summary

Common Services FunctionsThe following sections provide a brief description of the functions in the CS component.Review of the actual source code is recommended for further information.

Table 4-2. Common Services Field Declarations

Field Description

*cs_previous This is a link in the current node to the previous node structure forCS. It is part of the CS list, which is a doubly linked, circular list.

*cs_next This is a link in the current node to the next node structure for CS. Itis part of the CS list, which is a doubly linked, circular list.

cs_priority Denotes the task or HISR priority.

cs_padding This is used to align the CS structure on an even boundary. For mosttargets, this field is not used.

Component DescriptionsCSC_Place_On_List


CSC_Place_On_ListUsage

VOID CSC_Place_On_List (CS_NODE **head, CS_NODE *new_node)

Description

This function places the specified node at the end of the specified doubly linked circular list.


Component DescriptionsCSC_Priority_Place_On_List

December 15, 2006

CSC_Priority_Place_On_ListUsage

VOID CSC_Priority_Place_On_List (CS_NODE **head, CS_NODE *new_node)

Description

This function places the specified node on the list based upon its priority. The node is placedafter all other nodes on the list of equal or greater priority. Note that lower numerical valuesindicate greater priority.

Component DescriptionsCSC_Remove_From_List


CSC_Remove_From_ListUsage

VOID CSC_Remove_From_List (CS_NODE **head, CS_NODE *node)

Description

This function removes the specified node from the specified linked list.


Component DescriptionsInitialization Component (IN)

December 15, 2006

Initialization Component (IN)The initialization component (IN) is responsible for initializing the Nucleus PLUS system.There are typically two parts to the initialization process. The target-dependent portion isinitialized first by use of the ESAL component and then various Nucleus PLUS components areinitialized (timer, thread, and release). After Nucleus PLUS initialization is complete, NucleusMiddleware Initialization (NMI) executes. The last initialization function called isApplication_Initialize. The user defines its contents. After initialization is complete, control istransferred to the scheduling loop, TCCT_Schedule. See the Nucleus PLUS Reference Manualfor more detailed information about initialization.

Initialization FilesThe IN consists of four files. Each source file of the IN component is defined in the followingtable.

Initialization FunctionsThe following sections provide a brief description of the functions in the IN component.Review of the actual source code is recommended for further information.

Table 4-3. Initialization File Names

Field Description

in_extr.h All external interfaces to the IN are defined in this file.

inc_common.c This file contains the core function of the IN. The function that handlesthe basic system initialization service is defined in this file.

inct_common.c These files contain all of the calls to target dependent functions of the IN.

inct_pool.c

Component DescriptionsINC_Initialize


INC_InitializeUsage

VOID INC_Initialize (VOID *first_available_memory)

Description

This function is the main initialization function of the system. The thread and timer componentsare initialized by this function. After system initialization is complete, the Application_Initialize function is called. After all initialization is complete, this function calls TCCT_Schedule to start scheduling tasks.

Functions Called

RLC_Initialize

NU_MIC_INITIALIZE

TCIT_Initialize

TMIT_Initialize

INCT_Sys_Mem_Pools_Initialize

NMI_Initialize

Application_Initialize

TCCT_Schedule


Component DescriptionsOS_Init_Entry

December 15, 2006

OS_Init_EntryUsage

VOID OS_Init_Entry (VOID)

Description

This function calls all of the low-level, target dependent initialization functions. Once thisfunction is complete, control is transferred to the target independent initialization function,INC_Initialize.

Functions Called

ESAL_GE_RTE_Initialize

ESAL_GE_STK_Initialize

ESAL_GE_STK_SYSTEM_SP_SET

ESAL_GE_MEM_Initialize

ESAL_GE_INT_All_Disable

ESAL_GE_ISR_Initialize

ESAL_GE_TMR_OS_Timer_Start

INC_Initialize

Component DescriptionsINCT_Sys_Mem_Pools_Initialize


INCT_Sys_Mem_Pools_InitializeUsage

VOID INCT_Sys_Mem_Pools_Initialize (VOID *avail_mem_ptr)

Description

This function is called by INC_Initialize to create the system memory pools. This routinecreates two memory pools: cached and uncached. The size of each memory pool is determinedby ESAL. In the case where cached memory is not available on the target hardware, theavailable memory is split in half - each pool is allocated half of the total available memory. Thecreated memory pool control blocks are stored in the global variables System_Memory andUncached_System_Memory.

Functions Called

ESAL_GE_MEM_Remaining_Size_Get

ESAL_GE_MEM_First_Uncached_Get

DMC_Create_Memory_Pool

ERC_System_Error

Nucleus Middleware Initialization Component(NMI)

NMI provides a common and simple mechanism to initialize any supported middleware (MW).User applications and MW can also use NMI to track and synchronize on the initialization statusof other middleware. The NMI service works from a product registry which contains an entryfor several Nucleus middleware products that initialize using the NMI services.

Nucleus Middleware Initialization FilesThe NMI component consists of the follwing six files.

Table 4-4. NMI Component Initialization Files

Field Description

nmi_cfg.h This file contains definitions for each MW product supported byNMI. This is where a user sets a MW’s <PRODUCT>_NMI_INITdefinitions to NU_TRUE to cause the MW to be initialized.

nmid.c This file contains global data for each MW product supported byNMI. This is where the NMI Product Registry is defined.

nmi_defs.h Internal constants and data structures are defined in this file.

nmi_extr.h External interfaces to NMI are defined in this file.


Component DescriptionsNucleus Middleware Initialization Component (NMI)

December 15, 2006

How to Add New MW Products to the NMI ProductRegistry Array

NMI relies on a product registry array that contains entries for all supported middleware. Youcan add a new entry to the product registry array by making the following changes.

NoteEach product which supports NMI must document the <PRODUCT> name to use whenmaking these changes.

NMI requires the following resources:

NoteThe names of the external definitions are deliberately hard-coded so that nmid.c shouldnever include header files from MW products.

1. Add an Initialization Define to nmi_cfg.h

Add a definition like the following to nmi_cfg.h, where <PRODUCT> is the new MW’sunique product name, for example “NET” or “FILE”:

#define <PRODUCT>_NMI_INIT NU_TRUE /* Product */

nmi_cleanup.c All core NMI functions and static and global data structures arecontained in these files.

nmi_common.c

nmi_wait.c

nmie_cleanup.c These files contain the error checking function interfaces for thefunctions defined in nmi_cleanup.c, nmi_common.c, and nmi_wait.c.

nmie_common.c

nmie_wait.c

Table 4-5. Product Registry Array Values

Resource Name Description

<PRODUCT>_NMI_INIT

The MW’s NMI initialization definition

<PRODUCT>_NMI_Registration

The MW’s NMI registration function

<PRODUCT>NMI_Id

The MW’s NMI Id variable

Table 4-4. NMI Component Initialization Files (cont.)

Field Description



2. Add the MW’s External Definitions to nmi_cfg.h

Add required MW external definitions, as in the following example, to nmi_cfg.h, where<PRODUCT> is the new MW’s unique product name.

#if (<PRODUCT>_NMI_INIT == NU_TRUE)extern NMI_INIT_STATUS <PRODUCT>_NMI_Registration (NMI_MW_REG_DATA*);extern const char* <PRODUCT>_NMI_Id;#endif

3. Add References to External Definitions to the Product Registry in nmi_data.c

Add a product registry entry like the following to nmi_data.c, where <PRODUCT> isthe new MW’s unique product name.

#if (<PRODUCT>_NMI_INIT == NU_TRUE){&<PRODUCT>_NMI_Id, PLUS_SERIAL_NMI_Registration},

#endif

Nucleus Middleware Initialization Data Structures

Product Registration DataEvery product that supports NMI must fill in anNMI_MW_REG_DATA structure when itsregistration function is called.

Field Declarations

const CHAR* mw_id_ptrconst CHAR* mw_ver_ptrVOID* mw_cb_paramNMI_INIT_CB_PTR mw_init_cb_ptrNMI_CLEANUP_CB_PTR mw_cleanup_cb_ptr



December 15, 2006

Field Summary

Product Registry ArrayEvery product that supports NMI must have an NMI_PRODUCT_REGISTRY_ENTRY inNMI_Product_Registry. The product registry is a hard-coded array of MW that is known tosupport NMI.

Product Registry Array EntryThe NMI_PRODUCT_REGISTRY_ENTRY contains all the information required for a MW’sregistration function to be called and the ID string that identifies the MW.

Field Declarations

const CHAR **mw_id_ptrNMI_REG_FUNC_PTR mw_reg_func_ptr

Field Summary

Registered Products Data ListPertinent information for every MW product that successfully registers with NMI is kept on adoubly linked, circular list. Newly created NMI_PRODUCT_DATA is placed on the list and isnever removed from the list. The head pointer of this list is NMI_Product_Data_List

Table 4-6.

Field Description

mw_id_ptr MW ID (static product-specific null-terminated string)

mw_ver_ptr MW version (static product-specific null-terminated string)

mw_cb_param MW specified parameter for all callbacks (optional)

mw_init_cb_ptr MW Initialization callback pointer

mw_cleanup_cb_ptr MW cleanup callback pointer (optional)

Table 4-7.

Field Description

mw_id_ptr Pointer to the MW’s unique product id.

mw_reg_func_ptr Pointer to the MW’s registration function.

This function is called by NMI_MW_Registration during OSinitialization to register the MW with the NMI services



Figure 4-1. NMI Product Data List

Registered Product DataThe NMI_PRODUCT_DATA contains all the required information about a registered product,including the information it registered with NMI and its current initialization status.

Field Declarations

CS_NODE mw_list_nodeNMI_MW_REG_DATA* mw_reg_data_ptrNMI_INIT_STATUS mw_status

Field Summary

Nucleus Middleware Initialization Function and CallbackTypedefs

These typedefs are provided for MW as a reference. They serve to illustrate the functionsignature of the MW functions and callbacks used by NMI.

Table 4-8.

Field Description

mw_list_node Linked list node of created MW data structures

mw_reg_data_ptr Pointer to product’s registration data structure as filled in by theMW’s registration function

mw_status Initialization status of the product

Table 4-9.

enum Purpose

NMI_REG_FUNC_PTR Pointer to MW’s registration function

NMI_INIT_CB_PTR Pointer to MW’s initialization callback

NMI_CLEANUP_CB_PTR

Pointer to MW’s cleanup callback


Component DescriptionsNMI_REG_FUNC_PTR

December 15, 2006

NMI_REG_FUNC_PTRUsage

typedef NMI_INIT_STATUS (*NMI_REG_FUNC_PTR) (NMI_MW_REG*)

Description

Every product that supports NMI must have a registration function.

Component DescriptionsNMI_INIT_CB_PTR


NMI_INIT_CB_PTRUsage

typedef VOID (*NMI_INIT_CB_PTR) (NU_MEMORY_POOL*, NU_MEMORY_POOL*,VOID**, VOID*);

Description

Every product that supports NMI must have an initialization callback.


Component DescriptionsNMI_CLEANUP_CB_PTR

December 15, 2006

NMI_CLEANUP_CB_PTRUsage

typedef VOID (*NMI_INIT_CB_PTR) (VOID**, VOID*);

Description

Every product that supports NMI may optionally have a cleanup callback.

Nucleus Middleware Initialization Definitions

Table 4-10.

Symbol Purpose

NMI_SUPPORT Defined as NU_TRUE if PLUS supports NMI.

Component DescriptionsNMI_SUPPORT


NMI_SUPPORTUsage

#define NMI_SUPPORT NU_TRUE

Description

This definition indicates that the NMI service is supported. This value is not defined prior toPLUS 2.0.

Nucleus Middleware Initialization FunctionsThe following sections provide a brief description of the functions in the MW component.Review of the actual source code is recommended for further information.


Component DescriptionsNMI_Initialize

December 15, 2006

NMI_InitializeUsage

VOID NMI_Initialize (NU_MEMORY_POOL *mem_pool, NU_MEMORY_POOL*uncached_mem_pool)

Description

This function calls the registration functions of all the MW products in the NMI ProductRegistry array, and then invokes the initialization callbacks of all the registered products.

Functions Called

NMI_MW_Registration

NMI_MW_Initialization

ERC_System_Error

Component DescriptionsNMI_MW_Initialization


NMI_MW_InitializationUsage

static STATUS NMI_MW_Initialization (NU_MEMORY_POOL *mem_pool,NU_MEMORY_POOL* uncached_mem_pool)

Description

This function invokes the initialization callback of every MW product that successfullyregistered.

Functions Called

Each product’s initialization callback


Component DescriptionsNMI_MW_Registration

December 15, 2006

NMI_MW_RegistrationUsage

statis STATUS NMI_MW_Registration (NU_MEMORY_POOL *mem_pool,NU_MEMORY_POOL* uncached_mem_pool)

Description

This function calls the registration function of every MW product in the NMI Product Registryarray. It allocates and tracks all data associated with each product. The product registry is notused after this function returns.

Functions Called

Each product’s registration function

NU_Allocate_Memory

ESAL_GE_MEM_Clear

Each product’s registration function

CSC_Place_On_List

NU_Deallocate_Memory

Component DescriptionsNMI_Init_Status_Get


NMI_Init_Status_GetUsage

NMI_INIT_STATUS NMI_Init_Status_Get (const CHAR *mw_id_ptr)

Description

This function gets the MW product’s initialization status.

Functions Called

NMI_Product_Data_Find


Component DescriptionsNMI_Init_Status_Set

December 15, 2006

NMI_Init_Status_SetUsage

NMI_INIT_STATUS NMI_Init_Status_Set (const CHAR *mw_id_ptr, NMI_INIT_STATUSmw_status)

Description

This function sets the MW product's initialization status.

Functions Called


Component DescriptionsNMI_Wait_For_Init


NMI_Wait_For_InitUsage

NMI_INIT_STATUS NMI_Wait_For_Init (const CHAR *mw_id_ptr, UNSIGNEDtimeout_ticks)

Description

This function waits for a MW product to initialize. If the product fails to initialize then it returnsimmediately.

Functions Called


NU_Sleep


Component DescriptionsNMI_Cleanup_Invoke

December 15, 2006

NMI_Cleanup_InvokeUsage

NMI_INIT_STATUS NMI_Cleanup_Invoke (const CHAR *mw_id_ptr)

Description

This function executes the cleanup functionality for a given MW product.

Functions Called

The product’s cleanup callback, if there is one


Component DescriptionsNMI_Product_Data_Find


NMI_Product_Data_FindUsage

static NMI_PRODUCT_DATA *NMI_Product_Data_Find (const CHAR* mw_id_ptr)

Description

This function searches for the specified MW product id within the middleware data list. It willreturn a pointer to the MW data. If the MW data is not found, then it returns a NULL pointer.


Component DescriptionsNMIE_Init_Status_Get

December 15, 2006

NMIE_Init_Status_GetUsage

NMI_INIT_STATUS NMIE_Init_Status_Get (const CHAR *mw_id_ptr)

Description

This function performs error checking on the parameters supplied to the initialization status getfunction.

Functions Called

NMIE_Init_Status_Get

Component DescriptionsNMIE_Init_Status_Set


NMIE_Init_Status_SetUsage

NMI_INIT_STATUS NMIE_Init_Status_Set (const CHAR *mw_id_ptr, NMI_INIT_STATUSmw_status)

Description

This function performs error checking on the parameters supplied to the initialization status setfunction.

Functions Called

NMIE_Init_Status_Get


Component DescriptionsNMIE_Wait_For_Init

December 15, 2006

NMIE_Wait_For_InitUsage

NMI_INIT_STATUS NMIE_Wait_For_Init (const CHAR *mw_id_ptr, UNSIGNEDtimeout_ticks)

Description

This function performs error checking on the parameters supplied to the wait for initializationfunction.

Functions Called

NMIE_Wait_For_Init

Component DescriptionsNMIE_Cleanup_Invoke


NMIE_Cleanup_InvokeUsage

NMI_INIT_STATUS NMI_Cleanup_Invoke (const CHAR *mw_id_ptr)

Description

This function performs error checking on the parameters supplied to the cleanup callbackinvocation function.

Functions Called

NMIE_Cleanup_Invoke


Component DescriptionsThread Control Component (TC)

December 15, 2006

Thread Control Component (TC)The thread control component (TC) is responsible for managing the execution of competing,real-time Nucleus PLUS tasks and High Level Interrupt Routines (HISRs). A Nucleus PLUStask is a semi-independent program segment with a dedicated purpose. Most applications havemultiple tasks. In order to control the execution process, tasks are usually assigned a priority.Nucleus PLUS priorities range from 0 to 255, where 0 is the highest priority and 255 is thelowest priority. Higher priority tasks are executed before lower priority tasks. Additionally, alower priority task may be preempted when a higher priority task becomes ready, unlesspreemption has been disabled. Tasks are always in one of five states: executing, ready,suspended, terminated, or finished.

A Nucleus PLUS HISR is a scheduled piece of an ISR that is allowed to interact with NucleusPLUS services. HISRs have priorities ranging from 0 to 2 (configurable within tc_defs.h bymodifying the TC_HISR_PRIORITIES value), where 0 is the highest priority. See the NucleusPLUS Reference Manual for more detailed information about the TC component.

Thread Control FilesThe TC consists of nine files. Each source file of the TC component is defined in the followingtable.

Table 4-11. Thread Control Component Files

File Description

tc_defs.h This file contains constants and data structure definitionsspecific to the TC.

tc_extr.h All external interfaces to the TC are defined in this file.

tcd.c Global data structures for the TC are defined in this file.

tcit_common.c This file contains the initialization functions for the TC withtarget dependencies.

tcf_established.c These files contain the information gathering functions for theTC.

tcf_info.c

tcf_pointer.c



tcc_common.c These files contain all of the core functions of the TC.Functions that handle basic task services are defined in thesefiles.tcc_current_hisr.c

tcc_current_task.c

tcc_delete_hisr.c

tcc_delete_task.c

tcc_relinquish.c

tcc_resume.c

tcc_signal.c

tcc_suspend.c

tcc_task_sleep.c

tcc_terminate.c

tcs_preemption.c These files contain supplemental functions of the TC. Functionscontained in these files are typically used less frequently thanthe core functions.tcs_priority.c

tcs_signal.c

tcs_time_slice

tcce_common.c These files contain the error checking function interfaces for thecore functions defined in tcc_<function description>.c and tcct_<function_description>.c files.tcce_delete_hisr.c

tcce_delete_task.c

tcce_relinquish.c

tcce_reset_task.c

tcce_resume.c

tcce_suspend.c

tcce_task_sleep.c

tcce_terminate.c

tcse_preemption.c These files contain the error checking function interfaces for thesupplemental functions defined in tcs_<function description>.c

tcse_priority.c

tcse_signal.c

tcse_time_slice.c

tcfe_info.c These files contain the error checking function interfaces for thefact functions defined in tcf_<function description>.c.

Table 4-11. Thread Control Component Files (cont.)



December 15, 2006

Thread Control Data Structures

Created Tasks List

Figure 4-2. TCD Created Tasks List

Nucleus PLUS Tasks may be created and deleted dynamically. The Thread Control Block(TCB) for each created task is kept on a doubly linked, circular list. Newly created tasks areplaced at the end of the list, while deleted tasks are completely removed from the list. The headpointer of this list is TCD_Created_Tasks_List.

Total Tasks

The total number of currently created Nucleus PLUS tasks is contained in the variable TCD_Total_Tasks. The contents of this variable correspond to the number of TCBs on the created list.Manipulation of this variable is also done under the protection of TCD_List_Protect.

Created Task List ProtectionNucleus PLUS protects the integrity of the Created Tasks List from competing tasks and/orHISRs. This is done by using an internal protection structure called TCD_List_Protect. All taskcreation and deletion is done under the protection of TCD_List_Protect.

tcct_common.c These files contain core TC and scheduling functions with targetdependencies.

tcct_create.c

tcct_interrupts.c

tcct_register.c

tcct_reset_task.c

tcct_signal.c

tcst_signal.c These files contain supplemental functions for TC with targetdependencies.

Table 4-11. Thread Control Component Files (cont.)



Field Declarations

TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting

Field Summary

Priority ListTCD_Priority_List is an array of TCB pointers. Each element of the array is the head pointer ofthe list of tasks ready for execution at that priority. If the priority is NULL, there are no tasksready for execution at that priority. The array is indexed by priority.

NoteThe size of the TCD_Priority_List array is one larger than the number of configured taskpriorities (defined by TC_PRIORITIES within tc_defs.h). Because the highest arrayindex is not an actual task priority, its array element will always point to NULL. Thepurpose of this configuration is to allow the task scheduling algorithm to be moreefficient.

Table 4-12.

Field Description

tc_tcb_pointer Identifies the thread that currently has the protection.

tc_thread_waiting A flag indicating that one or more threads are waiting for theprotection.



December 15, 2006

Figure 4-3. TCD Priority List

Priority Groups

Figure 4-4. TCD Priority Groups

TCD_Priority_Groupcs is a 32-bit unsigned integer that is used as a bit map. Each bitcorresponds to an 8-priority group. For example, if bit 0 is set, at least one task of priority 0through 8 is ready for execution.



Sub-Priority Groups

Figure 4-5. TCD Sub-Priority Groups

Nucleus PLUS uses sub-priorities to determine the exact priority represented in the bit map.TCD_Sub_Priority_Groups is an array of sub-priority groups. In this array, index 0corresponds to priorities 0 through 8. Bit 0 of this element represents priority 0, while bit 7represents priority 7.

Lowest Bit SetTCD_Lowest_Set_Bit is simply a standard look-up table. The table is indexed by valuesranging from 1 to 255. The value at any position in the table contains the lowest set bit for thatvalue. This is used to determine the highest priority task represented in the previously definedbit maps. For example, the lowest bit set for the value of 7 is contained in index 7 of theTCD_Lowest_Set_Bit. In the table below, the value of 7 is shown to have bit 0 set, which iscorrect.

NoteThe TCD_Lowest_Set_Bit look-up table can be configured to be located in ROM orwithin RAM. To conserve RAM memory, changing the NU_MIN_RAM_ENABLEDconfiguration setting in plus_cfg.h to NU_TRUE will force this table to be in ROM(using the C const keyword). A likely side-effect of moving this table in ROM is slowerperformance due to longer memory read cycles.

Figure 4-6. TCD Lowest Set Bit



December 15, 2006

Execute TaskNucleus PLUS maintains a pointer to the task to execute. This pointer is called TCD_Execute_Task. Note that TCD_Execute_Task does not necessarily point to the currently executing task.There are several points in the system where this is true. Two common situations arise duringtask preemption and during task protection conflicts.

Highest Priority TaskThe Nucleus PLUS variable TCD_Highest_Priority contains the highest task priority ready forexecution. Note that this does not necessarily represent the priority of the currently executingtask. This is true if the currently executing task has preemption disabled or a protection relatedconflict exists. If no tasks are executing, this variable is set to the maximum task priority(defined by TC_PRIORITIES).

Highest Priority HISRThe Nucleus PLUS variable TCD_Highest_Priority_HISR contains the highest HISR priorityready for execution. Note that this does not necessarily represent the priority of the currentlyexecuting HISR. This may be true if a protection related conflict exists. If no HISRs areexecuting, this variable is set to the maximum HISR priority (defined by TC_HISR_PRIORITIES).

Created HISRs List

Figure 4-7. TCD Created HISRs List

TCD_Created_HISRs_List is the head pointer of the list of created High-Level Interrupt ServiceRoutines (HISR). If this pointer is NU_NULL, there are no HISRs currently created.

Total HISRsThe total number of currently created Nucleus PLUS HISRs is contained in the variable TCD_Total_HISRs. The contents of this variable correspond to the number of HCBs on the createdlist. Manipulation of this variable is also done under the protection of TCD_HISR_Protect.



Active HISR HeadsNucleus PLUS keeps an array of active HISR list head pointers. This list is called TCD_Active_HISR_Heads. There are 3 (default) HISR priorities available. The HISR priority is an indexinto this table. Priority/index 0 represents the highest priority and priority/index 2 representsthe lowest priority.

NoteThe size of the TCD_Active_HISR_Heads array is one larger than the number ofconfigured HISR priorities (defined by TC_HISR_PRIORITIES within tc_defs.h).Because the highest array index is not an actual HISR priority, its array element willalways point to NULL. The purpose of this configuration is to allow the HISRscheduling algorithm to be more efficient.

Active HISR TailsNucleus PLUS keeps an array of active HISR list tail pointers. There are three (default) HISRpriorities available. The HISR priority is an index into this table. Priority/index 0 represents thehighest priority and priority/index 2 represents the lowest priority.

Figure 4-8. TCD Active HISRs

Execute HISRTCD_Execute_HISR contains a pointer to the highest priority HISR to execute. If this pointeris NU_NULL, no HISRs are currently activated. Note that the current thread pointer is notalways equal to this pointer.



December 15, 2006

Current ThreadA pointer to the control block of the currently executing thread is stored in the variable TCD_Current_Thread. Therefore, this variable points to either a TC_TCB or a TC_HCB structure.

System ProtectNucleus PLUS protects the integrity of the system structures from competing tasks and/orHISRs. This is done by using an internal protection structure called TCD_System_Protect. Allsystem creation and deletion is done under the protection of TCD_System_Protect.

Field Declarations


Field Summary

LISR ProtectNucleus PLUS protects the integrity of LISRs from competing threads and/or HISRs. This isdone by using an internal protection structure called TCD_LISR_Protect. All LISR creation anddeletion is done under the protection of TCD_LISR_Protect.

Field Declarations


Field Summary

HISR ProtectNucleus PLUS protects the integrity of HISRs from competing threads and/or HISRs. This isdone by using an internal protection structure called TCD_HISR_Protect. All HISR creationand deletion is done under the protection of TCD_HISR_Protect.

Table 4-13.

Field Description

tcb_pointer Identifies the thread that currently has the protection.

tc_thread_waiting A flag indicating that one or more threads are waiting for the protection.

Table 4-14.

Field Description





Field Declarations


Field Summary

Unhandled InterruptNucleus PLUS maintains a variable that contains the last unhandled interrupt vector number insystem error conditions. This variable is TCD_Unhandled_Interrupt.

Unhandled ExceptionNucleus PLUS maintains a variable that contains the last unhandled exception vector number insystem error conditions. This variable is TCD_Unhandled_Exception.

In addition to saving the vector number of the unhandled exception, the stack frame pointer forthe unhandled exception is also saved. This stack frame can be used to determine the cause,location, etc of the exception. The variable that holds the stack frame pointer is TCD_Unhandled_Exception_SP.

Initialization ThreadNucleus PLUS utilizes the HISR control block TCD_Init_Thread during initialization. ThisHISR is not created and treated as a normal HISR. Instead, the HISR control block is simplypopulated with the minimal required data and TCD_Current_Thread is set to point to thiscontrol block. This allows the protection and stack checking components of Nucleus PLUS tobe written more efficiently for run-time usage.

Task Control BlockThe Task Control Block TC_TCB contains the task’s priority and other fields necessary forprocessing task control requests.

Field Declarations

CS_NODE tc_createdUNSIGNED tc_idCHAR tc_name[NU_MAX_NAME]DATA_ELEMENT tc_statusDATA_ELEMENT tc_delayed_suspend

Table 4-15.

Field Description





December 15, 2006

DATA_ELEMENT tc_priorityDATA_ELEMENT tc_preemptionUNSIGNED tc_scheduledUNSIGNED tc_cur_time_sliceVOID *tc_stack_startVOID *tc_stack_endVOID *tc_stack_pointerUNSIGNED tc_stack_sizeUNSIGNED tc_stack_minimumstruct TC_PROTECT_STRUCT *tc_current_protect[UNSIGNED tc_su_mode][struct MS_MODULE* tc_module]VOID *tc_saved_stack_ptrUNSIGNED tc_time_slicestruct TC_TCB_STRUCT *tc_ready_previousstruct TC_TCB_STRUCT *tc_ready_nextUNSIGNED tc_priority_groupTC_TCB_STRUCT **tc_priority_headDATA_ELEMENT *tc_sub_priority_ptrDATA_ELEMENT tc_sub_priorityDATA_ELEMENT tc_saved_statusDATA_ELEMENT tc_signal_activeDATA_ELEMENT tc_padding[PAD_3]VOID (*tc_entry)(UNSIGNED, VOID *)UNSIGNED tc_argcVOID *tc_argvVOID (*tc_cleanup)(VOID *)VOID *tc_cleanup_infostruct TC_PROTECT_STRUCT *tc_suspend_protectINT tc_timer_activeTM_TCB tc_timer_controlUNSIGNED tc_signalsUNSIGNED tc_enabled_signalsVOID (*tc_signal_handler)(UNSIGNED)UNSIGNED tc_system_reserved_1UNSIGNED tc_system_reserved_2UNSIGNED tc_system_reserved_3UNSIGNED tc_app_reserved_1Field Summary

Table 4-16. Field Summary for the Task Control Block

Field Description

tc_created This is the link node structure for tasks. It is linked into thecreated tasks list, which is a doubly linked, circular list.

tc_id This holds the internal task identification of 0x5441534B,which is an equivalent to ASCII TASK.

tc_name This is the user-specified, 8 character name for the task.

tc_status This is the task’s current status.

tc_delayed_suspend A flag that indicates if task is suspended.

tc_priority The current priority of the task.

tc_preemption A flag that determines if preemption is enabled.



tc_scheduled This indicates the task’s scheduled count.

tc_cur_time_slice This is the value of the current time-slice.

*tc_stack_start A pointer to the starting address for the task’s stack.

*tc_stack_end A pointer to the ending address for the task’s stack.

*tc_stack_pointers This is the task’s stack pointer.

tc_stack_size Stores the task’s stack size.

tc_stack_minimum The task’s minimum allowable stack size.

*tc_current_protect A pointer to the task’s current protection structure.

[tc_su_mode] The supervisor/user mode switch counter.

[tc_module] The pointer to the task’s module control block.

*tc_saved_stack_ptr The task’s previous stack pointer.

tc_time_slice The value for the task’s current time-slice.

*tc_ready_previous A pointer to the previously ready TCB.

*tc_ready_next A pointer to the TCB that is next on the ready list.

tc_priority_group The current mask of the priority group bit.

**tc_priority_head A pointer to the head of the priority list.

*tc_sub_priority_ptr A pointer to the priority sub-group.

tc_sub_priority The current mask of the priority sub-group bit.

tc_saved_status This is the previous task’s status.

tc_signal_active A flag indicating if the signal is active or not.

tc_padding This is used to align the task structure on an even boundary. Formost targets, this field is not used.

(*tc_entry) (UNSIGNED,VOID *)

This is the task entry function.

tc_argc An optional task argument.

*tc_argv An optional task argument.

(*tc_cleanup (VOID *) This is the task clean-up function.

*tc_cleanup_info This is a pointer to task clean-up information.

*tc_suspend_protect A pointer to the protection structure at the time of tasksuspension.

tc_timer_active A flag that determines if the timer is active.

tc_timer_control The timer control block.

Table 4-16. Field Summary for the Task Control Block (cont.)



December 15, 2006

HISR Control BlockThe HISR Control Block TC_HCB contains the HISR’s priority and other fields necessary forprocessing task control requests.

Field Declarations

CS_NODE tc_createdUNSIGNED tc_idCHAR tc_name[NU_MAX_NAME]DATA_ELEMENT tc_not_used_1DATA_ELEMENT tc_not_used_2DATA_ELEMENT tc_priorityDATA_ELEMENT tc_not_used_3UNSIGNED tc_scheduledUNSIGNED tc_cur_time_sliceVOID *tc_stack_startVOID *tc_stack_endVOID *tc_stack_pointerUNSIGNED tc_stack_sizeUNSIGNED tc_stack_minimumstruct TC_PROTECT_STRUCT tc_current_protect[UNSIGNED tc_su_mode][struct MS_MODULE *tc_module]struct TC_HCB_STRUCT *tc_active_nextUNSIGNED tc_activation_countVOID (*tc_entry)(VOID)UNSIGNED tc_system_reserved_1UNSIGNED tc_system_reserved_2UNSIGNED tc_system_reserved_3UNSIGNED tc_app_reserved_1

tc_signals Contains the current signals.

tc_enabled_signals Contains the enabled signals.

(*tc_signal_handler)(UNSIGNED)

This is the signal handling function.

tc_system_reserved_1 This is a reserved word for use by the system.



tc_app_reserved_1 This is a reserved word for use by the application.

Table 4-16. Field Summary for the Task Control Block (cont.)



Field Summary

Table 4-17. Field Summary for HISR Control Block

Field Description

tc_created This is the link node structure for HISRs. It is linked into thecreated HISRs list, which is a doubly linked, circular list.

tc_id This holds the internal HISR identification of 0x48495352,which is an equivalent to ASCII HISR.

tc_name This is the user-specified, 8 character name for the HISR.

tc_not_used_1 This field is a placeholder and is not used.


tc_priority This is the priority of the HISR.


tc_scheduled This is the HISR scheduled count.

tc_cur_time_slice This is the value of the current time-slice.

*tc_stack_start A pointer to the starting address for the HISR’s stack.

*tc_stack_end A pointer to the ending address for the HISR’s stack.

*tc_stack_pointer This is the HISR’s stack pointer.

*tc_stack_size Stores the HISR’s stack size.

*tc_stack_minimum The HISR’s minimum allowable stack size.

*tc_current_protect A pointer to the HISR’s current protection structure.

[tc_su_mode] The supervisor/user mode switch counter.

[tc_module] The pointer to the HISR’s module control block.

*tc_active_next A pointer to the next activated HISR.

tc_activation_count The activation counter for the HISR.

(*tc_entry) (VOID) This is the HISR’s entry function.




tc_app_reserved_1 This is a reserved word for use by the application.



December 15, 2006

Protection BlockNucleus PLUS protects the integrity of Nucleus PLUS data structures from competing tasksand/or HISRs. This is done by using an internal protection structure called TC_PROTECT.The structure points to the protection block currently being used by the thread. Nucleus PLUScan only protect one structure per thread at a time. All Nucleus PLUS data structure creationand deletion and any list access is done under the protection of TC_PROTECT.

Field Declarations


Field Summary

Thread Control FunctionsThe following sections provide a brief description of the functions in the TC component.Review of the actual source code is recommended for further information.

Table 4-18.

Field Description

*tc_tcb_pointer Identifies the thread that currently has the protection.


Component DescriptionsTCCT_Create_Task


TCCT_Create_TaskUsage

STATUS TCCT_Create_Task (NU_TASK *task_ptr, CHAR *name,VOID(*task_entry)(UNSIGNED, VOID *), UNSIGNED argc, VOID *argv, VOID*stack_address, UNSIGNED stack_size, OPTION priority, UNSIGNED time_slice,OPTION preempt, OPTION auto_start)

Description

This function creates a task and then places it on the list of created tasks. All the resourcesnecessary to create the task are supplied to this function. If specified, the newly created task isstarted. Otherwise, it is left in a suspended state.

Functions Called

CSC_Place_On_List

[HIC_Make_History_Entry]

TCC_Resume_Task

TMC_Init_Task_Timer

[TCCT_Check_Stack]

TCCT_Control_To_System

TCCT_Protect

TCCT_Unprotect

ESAL_AR_STK_Unsolicited_Set

[MSC_Bind_Module_Task]


Component DescriptionsTCC_Delete_Task

December 15, 2006

TCC_Delete_TaskUsage

STATUS TCC_Delete_Task (NU_TASK *task_ptr)

Description

This function deletes a task and removes it from the list of created tasks. It is assumed by thisfunction that the task is in a finished or terminated state. Note that this function does not freememory associated with the task’s control block or its stack. That is the responsibility of theapplication.

Functions Called

CSC_Remove_From_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCCT_Create_HISR


TCCT_Create_HISRUsage

STATUS TCCT_Create_HISR (NU_HISR *hisr_ptr, CHAR *name, VOID(*hisr_entry)(VOID), OPTION priority, VOID *stack_address,UNSIGNED stack_size)

Description

This function creates a HISR and then places it on the list of created HISRs. All the resourcesnecessary to create the HISR are supplied to this function. HISRs are always created in adormant state.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

[MSC_Bind_Module_HISR]

ESAL_TS_STK_Solicited_Set


Component DescriptionsTCC_Delete_HISR

December 15, 2006

TCC_Delete_HISRUsage

STATUS TCC_Delete_HISR (NU_HISR *hisr_ptr)

Description

This function deletes a HISR and removes it from the list of created HISRs. It is assumed bythis function that the HISR is in a non-active state. Note that this function does not free memoryassociated with the HISR’s control block or its stack. This is the responsibility of theapplication.

Functions Called



[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCCT_Reset_Task


TCCT_Reset_TaskUsage

STATUS TCCT_Reset_Task (NU_TASK *task_ptr, UNSIGNED argc,VOID *argv)

Description

This function resets the specified task. Note that a task reset can only be performed on tasks ina finished or terminated state. The task is left in an unconditional suspended state.

Functions Called


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

ESAL_AR_STK_Unsolicited_Set


Component DescriptionsTCC_Terminate_Task

December 15, 2006

TCC_Terminate_TaskUsage

STATUS TCC_Terminate_Task (NU_TASK * task_ptr)

Description

This function terminates the specified task. If the task is already terminated, this function doesnothing. If the task to terminate is currently suspended, the specified cleanup function is alsoinvoked to clean up suspension data structures.

Functions Called

Cleanup function


TCC_Suspend_Task

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

TCCT_Unprotect_Specific

TMC_Stop_Task_Timer

Component DescriptionsTCC_Resume_Task


TCC_Resume_TaskUsage

STATUS TCC_Resume_Task (NU_TASK *task_ptr, OPTION suspend_type)

Description

This function resumes a previously suspended task. The task must currently be suspended forthe same reason indicated by this request. If the task resumed is of higher priority than thecalling task and the current task is preemptable, this function returns a value of NU_TRUE. Ifno preemption is required, a NU_FALSE is returned.

Functions Called

[TCCT_Check_Stack]

TCCT_Set_Current_Protect

TCCT_Set_Execute_Task

TMC_Stop_Task_Timer


Component DescriptionsTCC_Resume_Service

December 15, 2006

TCC_Resume_ServiceUsage

STATUS TCC_Resume_Service (NU_TASK *task_ptr)

Description

This function provides a suitable interface to the actual service to resume a task.

Functions Called


TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCC_Suspend_Task


TCC_Suspend_TaskUsage

VOID TCC_Suspend_Task (NU_TASK *task_ptr, OPTION suspend_type, VOID (*cleanup)(VOID*), VOID*information, UNSIGNED timeout)

Description

This function suspends the specified task. If the specified task is the calling task, control istransferred back to the system.

Functions Called

HIC_Make_History_Entry


TCCT_Protect


TCCT_Protect_Switch

TCCT_Unprotect

TMC_Start_Task_Timer


Component DescriptionsTCC_Suspend_Service

December 15, 2006

TCC_Suspend_ServiceUsage

STATUS TCC_Susepend_Service (NU_TASK *task_ptr)

Description

This function provides a suitable interface to the actual service to suspend a task.

Functions Called


TCC_Suspend_Task

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCC_Task_Timeout


TCC_Task_TimeoutUsage

VOID TCC_Task_Timeout (NU_TASK *task_ptr)

Description

This function processes task suspension timeout conditions. Note that task sleep requests arealso considered a timeout condition.

Functions Called

Caller’s cleanup function

TCC_Resume_Task

[TCCT_Check_Stack]

TCCT_Protect


TCCT_Unprotect



Component DescriptionsTCC_Task_Sleep

December 15, 2006

TCC_Task_SleepUsage

VOID TCC_Task_Sleep (UNSIGNED ticks)

Description

This function provides task sleep suspensions. Its primary purpose is to interface with theactual task suspension function.

Functions Called


TCC_Suspend_Task

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCC_Relinquish


TCC_RelinquishUsage

VOID TCC_Relinquish (VOID)

Description

This function moves the calling task to the end of other tasks at the same priority level. Thecalling task does not execute again until all the other tasks of the same priority are given achance to execute.

Functions Called


[TCCT_Check_Stack]


TCCT_Protect


TCCT_Unprotect


Component DescriptionsTCC_Time_Slice

December 15, 2006

TCC_Time_SliceUsage

VOID TCC_Time_Slice (NU_TASK *task_prt)

Description

This function moves the specified task to the end of the other tasks at the same priority level. Ifthe specified task is no longer ready, this request is ignored.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect


TCCT_Unprotect

Component DescriptionsTCC_Current_Task_Pointer


TCC_Current_Task_PointerUsage

NU_TASK *TCC_Current_Task_Pointer (VOID)

Description

This function returns the pointer of the currently executing task. If the current thread is not atask thread, a NU_NULL is returned.


Component DescriptionsTCC_Current_HISR_Pointer

December 15, 2006

TCC_Current_HISR_PointerUsage

NU_HISR *TCC_Current_HISR_Pointer (VOID)

Description

This function returns the pointer of the currently executing HISR. If the current thread is not aHISR thread, a NU_NULL is returned.

Component DescriptionsTCC_Task_Shell


TCC_Task_ShellUsage

VOID TCC_Task_Shell (VOID)

Description

This function is a shell from which all application tasks are initially executed. The shell causesthe task to finish when control is returned from the application task. Also, the shell passes argcand argv arguments to the task’s entry function.

Functions Called

Task Entry Function

TCC_Suspend_Task

TCCT_Protect


Component DescriptionsTCC_Signal_Shell

December 15, 2006

TCC_Signal_ShellUsage

VOID TCC_Signal_Shell (VOID)

Description

This function processes signals by calling the task-supplied signal handling function. Whensignal handling is completed, the task is placed in the appropriate state.

Functions Called

task’s signal handling function

[TCCT_Check_Stack]

TCCT_Signal_Exit

TCCT_Protect


TCCT_Unprotect

Component DescriptionsTCC_Unhandled_Interrupt


TCC_Unhandled_InterruptUsage

VOID TCC_Unhandled_Interrupt (INT unhandled_vector)

Description

This function catches all unhandled interrupts and puts them in the system error handlingfunction.

Functions Called

ERC_System_Error


Component DescriptionsTCC_Unhandled_Exception

December 15, 2006

TCC_Unhandled_ExceptionUsage

VOID TCC_Unhandled_Exception (INT unhandled_vector, VOID *stack_pointer)

Description

This function catches all unhandled exceptions and puts them in the system error handlingfunction.

Functions Called

ERC_System_Error

Component DescriptionsTCCT_Register_LISR


TCCT_Register_LISRUsage

STATUS TCCT_Register_LISR (INT vector, VOID(*new_lisr) (INT), VOID (**old_lisr)(INT))

Description

This function registers the supplied LISR with the supplied vector number. If the suppliedLISR is NU_NULL, the supplied vector is de-registered. The previously registered LISR isreturned to the caller, along with the completion status.

Functions Called


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsTCCE_Create_Task

December 15, 2006

TCCE_Create_TaskUsage

STATUS TCCE_Create_Task (NU_TASK *task_ptr,CHAR *name,VOID(*task_entry)(UNSIGNED, VOID*),UNSIGNED argc, VOID *argv,VOID *stack_address,UNSIGNED stack_size,OPTION priority, UNSIGNED time_slice, OPTION preempt,OPTION auto_start)

Description

This function performs error checking on the parameters supplied to the create task function.

Functions Called

TCCT_Create_Task

Component DescriptionsTCCE_Create_HISR


TCCE_Create_HISRUsage

STATUS TCCE_Create_HISR (NU_HISR *hisr_ptr, CHAR *name, VOID(*hisr_entry)(VOID), OPTION priority, VOID *stack_address, UNSIGNED stack_size)

Description

This function performs error checking on the parameters supplied to the create HISR function.

Functions Called

TCCT_Create_HISR


Component DescriptionsTCCE_Delete_HISR

December 15, 2006

TCCE_Delete_HISRUsage

STATUS TCCE_Delete_HISR (NU_HISR *hisr_ptr)

Description

This function performs error checking on the parameters supplied to the delete HISR function.

Functions Called

TCC_Delete_HISR

Component DescriptionsTCCE_Delete_Task


TCCE_Delete_TaskUsage

STATUS TCCE_Delete_Task (NU_TASK *task_ptr)

Description

This function performs error checking on the parameters supplied to the delete task function.

Functions Called

TCC_Delete_Task


Component DescriptionsTCCE_Reset_Task

December 15, 2006

TCCE_Reset_TaskUsage

STATUS TCCE_Reset_Task (NU_TASK* task_ptr,UNSIGNED argc,VOID *argv)

Description

This function performs error checking on the parameters supplied to the reset task function.

Functions Called

TCCT_Reset_Task

Component DescriptionsTCCE_Terminate_Task


TCCE_Terminate_TaskUsage

STATUS TCCE_Terminate_Task (NU_TASK *task_ptr)

Description

This function performs error checking on the parameters supplied to the terminate task function.

Functions Called

TCC_Terminate_Task


Component DescriptionsTCCE_Resume_Service

December 15, 2006

TCCE_Resume_ServiceUsage

STATUS TCCE_Resume_Service (NU_TASK *task_ptr)

Description

This function performs error checking on the parameters supplied to the resume task function.

Functions Called

TCCE_Validate_Resume

TCC_Resume_Service

Component DescriptionsTCCE_Suspend_Service


TCCE_Suspend_ServiceUsage

STATUS TCCE_Suspend_Service (NU_TASK *task_ptr)

Description

This function performs error checking on the suspend service function.

Functions Called

TCC_Suspend_Service


Component DescriptionsTCCE_Relinquish

December 15, 2006

TCCE_RelinquishUsage

VOID TCCE_Relinquish (VOID)

Description

This function performs error checking for the relinquish function. If the current thread is not atask, this request is ignored.

Functions Called

TCC_Relinquish

Component DescriptionsTCCE_Task_Sleep


TCCE_Task_SleepUsage

VOID TCCE_Task_Sleep (UNSIGNED ticks)

Description

This function performs error checking for the task sleep function. If the current thread is not atask, this request is ignored.

Functions Called

TCC_Task_Sleep


Component DescriptionsTCCE_Suspend_Error

December 15, 2006

TCCE_Suspend_ErrorUsage

INT TCCE_Suspend_Error (VOID)

Description

This function checks for a suspend request error. Suspension requests are only allowed fromtask threads. A suspend request from any other thread is an error.

Component DescriptionsTCCE_Register_LISR


TCCE_Register_LISRUsage

STATUS TCCE_Register_LISR (INT vector, VOID(*new_lisr)(INT),VOID(**old_lisr)(INT))

Description

This function performs error checking on the parameters supplied to the register LISR function.

Functions Called

TCCT_Register_LISR


Component DescriptionsTCCE_Activate_HISR

December 15, 2006

TCCE_Activate_HISRUsage

STATUS TCCE_Activate_HISR (NU_HISR *hisr_ptr)

Description

This function performs error checking on the parameters supplied to the activate HISR function.

Functions Called

TCCT_Activate_HISR

Component DescriptionsTCCE_Validate_Resume


TCCE_Validate_ResumeUsage

STATUS TCCE_Validate_Resume (OPTION resume_type, NU_TASK *task_ptr)

Description

This function validates the resume service and resume driver calls with scheduling protectionaround the examination of the task status.

Functions Called


TCCT_Get_Current_Protect

TCCT_System_Protect

TCCT_System_Unprotect

TCCT_Unprotect


Component DescriptionsTCF_Established_Tasks

December 15, 2006

TCF_Established_TasksUsage

UNSIGNED TCF_Established_Tasks (VOID)

Description

This function returns the current number of established tasks. Tasks previously deleted are nolonger considered established.

Functions Called

[TCCT_Check_Stack]

Component DescriptionsTCF_Established_HISRs


TCF_Established_HISRsUsage

UNSIGNED TCF_Established_HISRs (VOID)

Description

This function returns the current number of established HISRs. HISRs previously deleted are nolonger considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsTCF_Task_Pointers

December 15, 2006

TCF_Task_PointersUsage

UNSIGNED TCF_Task_Pointers (NU_TASK **pointer_list, UNSIGNED maximum_pointers)

Description

This function builds a list of task pointers, starting at the specified location. The number of taskpointers placed in the list is equivalent to the total number of tasks or the maximum number ofpointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsTCF_HISR_Pointers


TCF_HISR_PointersUsage

UNSIGNED TCF_HISR_Pointers (NU_HISR **pointer_list, UNSIGNED maximum_pointers

)

Description

This function builds a list of HISR pointers, starting at the specified location. The number ofHISR pointers placed in the list is equivalent to the total number of HISRs or the maximumnumber of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsTCF_Task_Information

December 15, 2006

TCF_Task_InformationUsage

STATUS TCF_Task_Information (NU_TASK *task_ptr, CHAR *name,DATA_ELEMENT*status,UNSIGNED *scheduled_count,DATA_ELEMENT *priority, OPTION*preempt,UNSIGNED *time_slice,VOID **stack_base, UNSIGNED *stack_size,UNSIGNED *minimum_stack)

Description

This function returns information about the specified task. However, if the supplied task pointeris invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsTCF_HISR_Information


TCF_HISR_InformationUsage

STATUS TCF_HISR_Information (NU_HISR *hisr_ptr, CHAR *name, UNSIGNED*scheduled_count,_DATA_ELEMENT *priority,VOID **stack_base, UNSIGNED*stack_size, UNSIGNED minimum_stack)

Description

This function returns information about the specified HISR. However, if the supplied HISRpointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsTCIT_Initialize

December 15, 2006

TCIT_InitializeUsage

VOID TCIT_Initialize (VOID)

Description

This function initializes the data structures that control the operation of the TC component. Thesystem is initialized as idle.

Component DescriptionsTCS_Change_Priority


TCS_Change_PriorityUsage

OPTION TCS_Change_Priority (NU_TASK *task_ptr, OPTION new_priority)

Description

This function changes the priority of the specified task. The priority of a suspended or a readytask can be changed. If the new priority requires a context switch, control is transferred back tothe system.

Functions Called


[TCCT_Check_Stack]


TCCT_Protect


TCCT_Unprotect


Component DescriptionsTCS_Change_Preemption

December 15, 2006

TCS_Change_PreemptionUsage

OPTION TCS_Change_Preemption (OPTION preempt)

Description

This function changes the preemption posture of the calling task. Preemption for a task may beenabled or disabled. If it is disabled, the task runs until it suspends or relinquishes. If apreemption is pending, a call to this function to enable preemption causes a context switch.

Functions Called


[TCCT_Check_Stack]


TCCT_Protect


TCCT_Unprotect

Component DescriptionsTCS_Change_Time_Slice


TCS_Change_Time_SliceUsage

UNSIGNED TCS_Change_Time_Slice (NU_TASK *task_ptr, UNSIGNED time_slice)

Description

This function changes the time-slice of the specified task. A time-slice value of 0 disables timeslicing for the specified task.

Functions Called


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsTCS_Control_Signals

December 15, 2006

TCS_Control_SignalsUsage

UNSIGNED TCS_Control_Signals (UNSIGNED enable_signal_mask)

Description

This function enables the specified signals and returns the previous enable signal value back tothe caller. If a newly enabled signal is present and a signal handler is registered, signal handlingis started.

Functions Called


TCC_Signal_Shell

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCS_Receive_Signals


TCS_Receive_SignalsUsage

UNSIGNED TCS_Receive_Signals (VOID)

Description

This function returns the current signals back to the caller. Note that the signals are clearedautomatically.

Functions Called


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsTCS_Register_Signal_Handler

December 15, 2006

TCS_Register_Signal_HandlerUsage

STATUS TCS_Register_Signal_Handler (VOID (*signal_handler)(UNSIGNED))

Description

This function registers a signal handler for the calling task. Note that if an enabled signal ispresent and this is the first registered signal handler call, the signal is processed immediately.

Functions Called


TCC_Signal_Shell

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsTCST_Send_Signals


TCST_Send_SignalsUsage

STATUS TCST_Send_Signals (NU_TASK *task_ptr, UNSIGNED signals)

Description

This function sends the specified task the specified signals. If enabled, the specified task is setupin order to process the signals.

Functions Called


TCC_Resume_Task

TCC_Signal_Shell

[TCCT_Check_Stack]


TCCT_Protect

TCCT_Unprotect



Component DescriptionsTCSE_Change_Priority

December 15, 2006

TCSE_Change_PriorityUsage

OPTION TCSE_Change_Priority (NU_TASK *task_ptr, OPTION new_priority)

Description

This function performs error checking for the change priority service. If an error is detected,this service is ignored and the requested priority is returned.

Functions Called

TCS_Change_Priority

Component DescriptionsTCSE_Change_Preemption


TCSE_Change_PreemptionUsage

OPTION TCSE_Change_Preemption (OPTION preempt)

Descripton

This function performs error checking on the change preemption service. If the current thread isnot a task thread, this request is ignored.

Functions Called

TCS_Change_Preemption


Component DescriptionsTCSE_Change_Time_Slice

December 15, 2006

TCSE_Change_Time_SliceUsage

UNSIGNED TCSE_Change_Time_Slice (NU_TASK *task_ptr, UNSIGNED time_slice)

Description

This function performs error checking on the change time-slice service. If the specified taskpointer is invalid, this request is ignored.

Functions Called

TCS_Change_Time_Slice

Component DescriptionsTCSE_Control_Signals


TCSE_Control_SignalsUsage

UNSIGNED TCSE_Control_Signals (UNSIGNED enable_signal_mask)

Description

This function checks to see if the call is being made from a non-task thread. If so, the request issimply ignored.

Functions Called

TCS_Control_Signals


Component DescriptionsTCSE_Receive_Signals

December 15, 2006

TCSE_Receive_SignalsUsage

UNSIGNED TCSE_Receive_Signals (VOID)

Description

This function determines whether or not the call is being made from a task thread of execution.If not, the call is ignored.

Functions Called

TCS_Receive_Signals

Component DescriptionsTCSE_Register_Signal_Handler


TCSE_Register_Signal_HandlerUsage

STATUS TCSE_Register_Signal_Handler (VOID (*signal_handler)(UNSIGNED))

Description

This function determines whether or not the caller is a task. If the caller is not a task and/or if thesupplied signal handling function pointer is NULL, an appropriate error status is returned.

Functions Called

TCS_Register_Signal_Handler


Component DescriptionsTCSE_Send_Signals

December 15, 2006

TCSE_Send_SignalsUsage

STATUS TCSE_Send_Signals (NU_TASK *task_ptr,UNSIGNED signals)

Description

This function checks for an invalid task. If an invalid task is selected, an error is returned.

Functions Called

TCST_Send_Signals

Component DescriptionsTCCT_Control_Interrupts


TCCT_Control_InterruptsUsage

INT TCCT_Control_Interrupts (R1 new_level)

Description

This function enables and disables interrupts as specified by the caller. Interrupts disabled bythis call are left disabled until another call is made to enable them.


Component DescriptionsTCCT_Check_Stack

December 15, 2006

TCCT_Check_StackUsage

UNSIGNED TCCT_Check_Stack (VOID)

Description

This function checks the current stack for overflow / underflow conditions. Additionally, thisfunction keeps track of the minimum amount of stack space for the calling thread and returnsthe current available stack space.

Functions Called

ERC_System_Error

ESAL_AR_STK_SP_Get

Component DescriptionsTCCT_Schedule


TCCT_ScheduleUsage

VOID TCCT_Schedule (VOID)

Description

This function waits for a thread to become ready. Once a thread is ready, this function initiatesa transfer of control to that thread.

Functions Called

ESAL_AR_STK_Unsolicited_Restore

ESAL_TS_STK_Solicited_Restore


Component DescriptionsTCCT_Control_To_System

December 15, 2006

TCCT_Control_To_SystemUsage

VOID TCCT_Control_To_System (VOID)

Description

This function returns control from a thread to the system. Note that this service is called in asolicited manner, i.e., it is not called from an interrupt thread. Registers required by thecompiler to be preserved across function boundaries are saved by this function. Note that this isusually a subset of the total number of available registers. Also note that the call to ESAL_TS_STK_Solicited_Switch results in a call to the function TCCT_Schedule.

Functions Called

ESAL_TS_STK_Solicited_Switch

Component DescriptionsTCCT_Signal_Exit


TCCT_Signal_ExitUsage

VOID TCCT_Control_To_System (VOID)

Description

This function exits from a signal handler. The primary purpose of this function is to clear thescheduler protection and switch the stack pointer back to the normal task’s stack pointer.

Functions Called

TCCT_Schedule


Component DescriptionsTCCT_Current_Thread

December 15, 2006

TCCT_Current_ThreadUsage

VOID *TCCT_Current_Thread (VOID)

Description

This function returns the current thread pointer. The use of this function is defined by the valueof ESAL_AR_PTR_ACCESS within the ESAL component.

Component DescriptionsTCCT_Set_Execute_Task


TCCT_Set_Execute_TaskUsage

VOID TCCT_Set_Execute_Task (R1 TC_TCB *task)

Description

This function sets the global variable for the currently executing task. This function is onlyused on architectures where setting the value requires more than one instruction. The use of thisfunction is defined by the value of ESAL_AR_PTR_ACCESS within the ESAL component.


Component DescriptionsTCCT_Protect

December 15, 2006

TCCT_ProtectUsage

VOID TCCT_Protect (R1 TC_PROTECT *protect)

Description

This function protects against multiple thread access. If another thread (TASK or HISR) ownsthe requested protection structure, then that thread will be scheduled to run until it releases theprotection structure. At that time, the thread is suspended, and control is returned to the threadexecuting the TCCT_Protect call. This prevents lower priority tasks from blocking higherpriority threads trying to obtain a protection structure.

Functions Called


Component DescriptionsTCCT_Unprotect


TCCT_UnprotectUsage

VOID TCCT_Unprotect (VOID)

Description

This function releases protection of the currently active thread. If the caller is not an activethread, then this request is ignored. The call to ESAL_TS_STK_Solicited_ Switch will result ina call to TCCT_Schedule.

Functions Called



Component DescriptionsTCCT_Unprotect_Specific

December 15, 2006

TCCT_Unprotect_SpecificUsage

VOID TCCT_Unprotect_Specific (R1 TC_PROTECT *protect)

Description

This function releases a specific protection structure. The call to ESAL_TS_STK_Solicited_Switch will result in a call to TCCT_Schedule.

Functions Called


Component DescriptionsTCCT_Set_Current_Protect


TCCT_Set_Current_ProtectUsage

VOID TCCT_Set_Current_Protect (R1 TC_PROTECT *protect)

Description

This function sets the current protection field of the current thread’s control block to thespecified protection pointer. The use of this function is defined by the value of ESAL_AR_PTR_ACCESS within the ESAL component.


Component DescriptionsTCCT_Get_Current_Protect

December 15, 2006

TCCT_Get_Current_ProtectUsage

TC_PROTECT *TCCT_Get_Current_Protect (VOID)

Description

This function gets the current protection field of the current thread’s control block to thespecified protection pointer. The use of this function is defined by the value of ESAL_AR_PTR_ACCESS within the ESAL component

Component DescriptionsTCCT_Protect_Switch


TCCT_Protect_SwitchUsage

VOID TCCT_Protect_Switch (R1 TC_TCB *switch_thread)

Description

This function waits until a specific task no longer has any protection associated with it. This isnecessary since tasks cannot be suspended or terminated unless they have released all of theirprotection.

Functions Called



Component DescriptionsTCCT_Dispatch_LISR

December 15, 2006

TCCT_Dispatch_LISRUsage

VOID **TCCT_Dispatch_LISR (INT vector, VOID *stack_pointer)

Description

This function is the non-nested interrupt service function for Nucleus PLUS. It utilizes theESAL components to execute the appropriate interrupt service function and perform post-interrupt processing necessary for the OS. This handler is registered with ESAL duringinitialization.

Functions Called

TCCT_Schedule

Registered Interrupt Service Routine

Component DescriptionsTCCT_Dispatch_Nested_LISR


TCCT_Dispatch_Nested_LISRUsage

VOID TCCT_Dispatch_Nested_LISR (INT vector)

Description

This function is the nested interrupt service function for Nucleus PLUS. It utilizes the ESALcomponents to execute the appropriate interrupt service function and perform post-interruptprocessing necessary for the OS. This handler is registered with ESAL during initialization.

Functions Called

Registered Interrupt Service Routine


Component DescriptionsTCCT_Activate_HISR

December 15, 2006

TCCT_Activate_HISRUsage

STATUS TCCT_Activate_HISR (R1 TC_HCB *hisr)

Description

This function activates the specified HISR. If the HISR is already activated, the HISR’sactivation count is simply incremented. Otherwise, the HISR is placed on the appropriate HISRpriority list in preparation for execution.

Component DescriptionsTCCT_HISR_Shell


TCCT_HISR_ShellUsage

VOID TCCT_HISR_Shell (VOID)

Description

This function is the execution shell of each and every HISR. If the HISR has completed itsprocessing, this shell function exits back to the system. Otherwise, it sequentially calls theHISR function until the activation count goes to zero.

Functions Called

hisr -> tc_entry


TCCT_Schedule


Component DescriptionsTimer Component (TM)

December 15, 2006

Timer Component (TM)The timer component (TM) is responsible for processing all Nucleus PLUS timer facilities. Thebasic unit of time for a Nucleus PLUS timer is a tick, which corresponds to a single hardwaretimer interrupt. Nucleus PLUS timers can be applied at the application level to execute aparticular function at timer expiration. Timers can also apply to tasks and are used to providetask sleeping and service call suspension timeouts. See the Nucleus PLUS Reference Manualfor more detailed information about timers.

Timer FilesThe TM consists of nine files. Each source file of the TM is defined in the following table.

Table 4-19. Timer File Names

File Description

tm_defs.h This file contains constants and data structure definitions specific to theTM.

tm_extr.h All external interfaces to the TM are defined in this file.

tmd.c Global data structures for the TM are defined in this file.

tmif_common.c This file contains TM initialization functions with target dependencies.

tmc_common.c This file contains all of the core functions of the TM. Functions thathandle basic start-timer and stop-timer services are defined in this file.

tms_control.c These files contain supplemental functions of the TM. Functionscontained in this file are typically used less frequently than the corefunctions.tms_create.c

tms_delete.c

tms_reset.c

tmse_control.c These files contain the error checking function interfaces for thesupplemental functions defined in tms_<function description>.c.

tmse_create.c

tmse_delete.c

tmse_reset.c

tmct_common.c These files contain TM core functions with target dependencies.

Component DescriptionsTimer Component (TM)


Timer Data Structures

Created Timers ListNucleus PLUS application timers may be created and deleted dynamically. The Timer ControlBlock (APP_TCB) for each created timer is kept on a doubly linked, circular list. Newlycreated timers are placed at the end of the list, while deleted timers are completely removedfrom the list. The head pointer of this list is TMD_Created_Timers_List. The Created TimersList is used exclusively for application timers.

Figure 4-9. TMD Created Timers List

Created Timer List ProtectionNucleus PLUS protects the integrity of the Created Timers List from competing tasks and/orHISRs. This is done by using an internal protection structure called TMD_Created_List_Protect. All timer creation and deletion is done under the protection of TMD_Created_List_Protect.

Field Declarations


Field Summary

Table 4-20.

Field Description




Component DescriptionsActive Timers List

December 15, 2006

Total TimersThe total number of currently created Nucleus PLUS timers is contained in the variable TMD_Total_Timers. The contents of this variable correspond to the number of TCBs on the createdlist. Manipulation of this variable is also done under the protection of TMD_Created_List_Protect.

Active Timers ListFigure 4-10. TMD Active Timers List

Nucleus PLUS active timers are maintained on a doubly linked, circular list. TMD_Active_Timers_List is the head pointer to this list. If this pointer is NULL, there are no timers active.The timer list supports both application timers and task timers. Task timer structures reside inthe task’s TCB. The timer list is maintained in order of expiration time. The remaining time is indelta expirations, not absolute time. This is done in order to avoid adjusting the entire list onevery timer interrupt. A timer with a remaining time of zero is considered to be expired.

Active List BusyNucleus PLUS protects the integrity of the Active Timers List from competing tasks and/orHISRs. This is done by using a protection flag called TMD_Active_List_Busy. All active timerlist additions and deletions are done under the protection of TMD_Active_List_Busy.



System ClockNucleus PLUS maintains a continually incrementing system clock called TMD_System_Clock.The clock is incremented by one each timer interrupt.

Timer StartNucleus PLUS stores the value of the last timer request in the variable TMD_Timer_Start.

TimerThe variable TMD_Timer is a countdown timer that is used to represent the smallest activetimer value in the system. When a timer expires, this variable has a value of zero.

Timer StateTMD_Timer_State indicates the state of the timer variable. If the state is active, the timercounter is decremented. If the state is expired, the timer HISR and timer task are initiated toprocess the expiration. If the state indicates that the timer is not active, the timer counter isignored.

Time-slice TaskTMD_Time_Slice_Task is a pointer to the TCB of the task to time-slice. This pointer is set upin the timer interrupt when a time-slice timer has expired.

HISRTMD_HISR is the timer HISR’s control block.

HISR StackTMD_HISR_Stack is the memory area reserved for the timer HISR.

Timer Control BlockThe Timer Control Block TM_TCB contains the remaining time and other fields necessary forprocessing timer requests.

Field Declarations

INT tm_timer_typeUNSIGNED tm_remaining_timeVOID *tm_informationstruct TM_TCB_STRUCT *tm_next_timerstruct TM_TCB_STRUCT *tm_previous_timer



December 15, 2006

Field Summary

Application Timer Control BlockThe Application Timer Control Block TM_APP_TCB contains a pointer to the timer expirationfunction and other fields necessary for processing application timer requests.

Field Declarations

CS_NODE tm_createdUNSIGNED tm_idCHAR tm_name[NU_MAX_NAME]VOID (*tm_expiration_routine)(UNSIGNED)UNSIGNED tm_expiration_idINT tm_enabledUNSIGNED tm_expirationsUNSIGNED tm_initial_timeUNSIGNED tm_reschedule_timeTM_TCB tm_actual_timer

Table 4-21.

Field Description

tm_timer_type Indicates if the timer is for an application or a task.

tm_remaining_time This stores the amount of time remaining after expiration of theprevious timer occurs. The true expiration is the sum of allprevious timer’s remaining time on the active list

*tm_information A pointer to general information about the timer.

*tm_next_timer A pointer to the next timer in the list.

*tm_previous_timer A pointer to the previous timer in the list.



Field Summary

Timer FunctionsThe following sections provide a brief description of the functions in the TM. Review of theactual source code is recommended for further information.

Table 4-22.

Field Description

tm_created This is the link node structure for timers. It is linked into thecreated timers list, which is a doubly linked, circular list.

tm_id This holds the internal timer identification of 0x54494D45,which is an equivalent to ASCII TIME.

tm_name This is the user-specified, 8 character name for the timer.

*tm_expiration_routine A pointer to the timer expiration function.

tm_expiration_id This is the name of the expiration.

tm_enabled A flag that determines if the timer is enabled.

tm_expirations This stores the number of timer expirations.

tm_initial_time Stores the initial starting time for the timer.

tm_reschedule_time Stores the reschedule time for the timer.

tm_actual_timer The actual timer TCB.


Component DescriptionsTMC_Init_Task_Timer

December 15, 2006

TMC_Init_Task_TimerUsage

VOID TMC_Init_Task_Timer (TM)TCB *timer, VOID *information)

Description

This function is responsible for initializing the supplied task timer.

Component DescriptionsTMC_Start_Timer


TMC_Start_TimerUsage

VOID TMC_Start_Timer (TM_TCB *timer, UNSIGNED time)

Description

This function is responsible for starting both application and task timers.

Functions Called

TMCT_Read_Timer

TMCT_Adjust_Timer

TMCT_Enable_Timer


Component DescriptionsTMC_Stop_Timer

December 15, 2006

TMC_Stop_TimerUsage

VOID TMC_Stop_Timer (TM_TCB *timer)

Description

This function is responsible for stopping both application and task timers.

Functions Called

TMCT_Disable_Timer

Component DescriptionsTMC_Timer_HISR


TMC_Timer_HISRUsage

VOID TMC_Timer_HISR (VOID)

Description

This function is responsible for high level interrupt processing of a timer expiration. If anapplication timer has expired, the timer expiration function is called. Otherwise, if the time-slicetimer has expired, time-slice processing is invoked.

Functions Called

TCC_Time_Slice

TMC_Timer_Expiration

TMCT_Retrieve_TS_Task


Component DescriptionsTMC_Timer_Expiration

December 15, 2006

TMC_Timer_ExpirationUsage

VOID TMC_Timer_Expiration (VOID)

Description

This function is responsible for processing all task timer expirations. This includes applicationtimers and basic task timers that are used for task sleeping and timeouts.

Functions Called

expiration_function

TCC_Task_Timeout

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsTMF_Established_Timers


TMF_Established_TimersUsage

UNSIGNED TMF_Established_Timers (VOID)

Description

This function returns the current number of established timers. Timers previously deleted areno longer considered established.

Functions Called

TCCT_Check_Stack]


Component DescriptionsTMF_Get_Remaining_Time

December 15, 2006

TMF_Get_Remaining_TimeUsage

UNSIGNED TMF_Get_Remaining_Time (NU_TIMER *timer, UNSIGNED *remaining_time)

Description

This function retrieves the remaining time before the expiration of the specified timer.

Functions Called

TCCT_System_Protect

TMCT_Read_Timer

TCT_Unprotect

Component DescriptionsTMF_Timer_Pointers


TMF_Timer_PointersUsage

UNSIGNED TMF_Timer_Pointers (NU_TIMER **pointer_list,UNSIGNEDmaximum_pointers)

Description

This function builds a list of timer pointers, starting at the specified location. The number oftimer pointers placed in the list is equivalent to the total number of timers or the maximumnumber of pointers specified in the call.

Functions Called

TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsTMF_Timer_Information

December 15, 2006

TMF_Timer_InformationUsage

STATUS TMF_Timer_Information (NU_TIMER *timer_ptr, CHAR *name, OPTION *enable,UNSIGNED *expirations, UNSIGNED *id, UNSIGNED*initial_time, UNSIGNED*reschedule_time)

Description

This function returns information about the specified timer. However, if the supplied timerpointer is invalid, the function simply returns an error status.

Functions Called

TCCT_Check_Stack

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsTMIT_Initialize


TMIT_InitializeUsage

VOID TMIT_Initialize (VOID)

Description

This function initializes the data structures that control the operation of the Timer Managementcomponent. There are no application timers created initially.

Functions Called

ESAL_GE_TMR_OS_ISR_Register

ERC_System_Error

TCCT_Create_HISR

TCCE_Create_HISR


Component DescriptionsTMS_Create_Timer

December 15, 2006

TMS_Create_TimerUsage

STATUS TMS_Create_Timer (NU_TIMER *timer_ptr, CHAR *name, VOID(*expiration_routine)(UNSIGNED),UNSIGNED id, UNSIGNED initial_time, UNSIGNEDreschedule_time, OPTION enable)

Description

This function creates an application timer and places it on the list of created timers. The timer isactivated if designated by the enable parameter.

Functions Called

CSC_Place_On_List


TCCT_Check_Stack

TCCT_Protect

TCCT_Unprotect

TMS_Control_Timer

Component DescriptionsTMS_Delete_Timer


TMS_Delete_TimerUsage

STATUS TMS_Delete_Timer (NU_TIMER *timer_ptr)

Description

This function deletes an application timer and removes it from the list of created timers.

Functions Called



[TCCT_Check_Stack]

TCCT_Protect

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsTMS_Reset_Timer

December 15, 2006

TMS_Reset_TimerUsage

STATUS TMS_Reset_Timer (NU_TIMER*timer_ptr,VOID(*expiration_routine)(UNSIGNED),UNSIGNED initial_time,UNSIGNEDreschedule_time, OPTION enable)

Description

This function resets the specified application timer. Note that the timer must be in a disabledstate prior to this call. The timer is activated after it is reset if the enable parameter specifiesautomatic activation.

Functions Called


[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect

TMS_Control_Timer

Component DescriptionsTMS_Control_Timer


TMS_Control_TimerUsage

STATUS TMS_Control_Timer (NU_TIMER *app_timer, OPTION enable)

Description

This function either enables or disables the specified timer. If the timer is already in the desiredstate, simply leave it alone.

Functions Called


[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect

TMC_Start_Timer

TMC_Stop_Timer


Component DescriptionsTMSE_Create_Timer

December 15, 2006

TMSE_Create_TimerUsage

STATUS TMSE_Create_Timer (NU_TIMER *timer_ptr, CHAR *name, VOID(*expiration_routine)(UNSIGNED),UNSIGNED id UNSIGNED initial_time,UNSIGNEDreschedule_time,OPTION enable)

Description

This function performs error checking on the parameters supplied to the create timer function.

Functions Called

TMS_Create_Timer

Component DescriptionsTMSE_Delete_Timer


TMSE_Delete_TimerUsage

STATUS TMSE_Delete_Timer (NU_TIMER *timer_ptr)

Description

This function performs error checking on the parameters supplied to the delete timer function.

Functions Called

TMS_Delete_Timer


Component DescriptionsTMSE_Reset_Timer

December 15, 2006

TMSE_Reset_TimerUsage

STATUS TMSE_Reset_Timer (NU_TIMER *timer_ptr,VOID(*expiration_routine)(UNSIGNED),UNSIGNED initial_time,UNSIGNEDreschedule_time,OPTION enable)

Description

This function performs error checking on the parameters supplied to the reset timer function.

Functions Called

TMS_Reset_Timer

Component DescriptionsTMSE_Control_Timer


TMSE_Control_TimerUsage

STATUS TMSE_Control_Timer (NU_TIMER *timer_ptr, OPTION enable)

Description

This function performs error checking on the parameters supplied to the control timer function.

Functions Called

TMS_Control_Timer


Component DescriptionsTMCT_Set_Clock

December 15, 2006

TMCT_Set_ClockUsage

VOID TMCT_Set_Clock (R1 UNSIGNED new_value)

Description

This function sets the system clock to the specified value. The use of this function is defined bythe ESAL_AR_32BIT_ACCESS value set in ESAL.

Component DescriptionsTMCT_Retrieve_Clock


TMCT_Retrieve_ClockUsage

UNSIGNED TMCT_Retrieve_Clock (VOID)

Description

This function returns the current value of the system clock. The use of this function is definedby the ESAL_AR_32BIT_ACCESS value set in ESAL.


Component DescriptionsTMCT_Increment_Clock

December 15, 2006

TMCT_Increment_ClockUsage

VOID TMCT_Increment_Clock (VOID)

Description

This function increments the system clock by one. The use of this function is defined by theESAL_AR_32BIT_ACCESS value set in ESAL.

Component DescriptionsTMCT_Read_Timer


TMCT_Read_TimerUsage

UNSIGNED TMCT_Read_Timer (VOID)

Description

This function returns the current value of the countdown timer. The use of this function isdefined by the ESAL_AR_32BIT_ACCESS value set in ESAL.


Component DescriptionsTMCT_Enable_Timer

December 15, 2006

TMCT_Enable_TimerUsage

VOID TMCT_Enable_Timer (R1 UNSIGNED time)

Description

This function enables the countdown timer with the specified value.

Component DescriptionsTMCT_Adjust_Timer


TMCT_Adjust_TimerUsage

VOID TMCT_Adjust_Timer (R1 UNSIGNED time)

Description

This function adjusts the countdown timer with the specified value - if the new value is less thanthe current.


Component DescriptionsTMCT_Retrieve_TS_Task

December 15, 2006

TMCT_Retrieve_TS_TaskUsage

NU_TASK *TMCT_Retrieve_TS_Task (VOID)

Description

This function returns the time-sliced task pointer. The use of this function is defined by theESAL_AR_PTR_ACCESS_ACCESS value set in ESAL.

Component DescriptionsTMCT_Timer_Interrupt


TMCT_Timer_InterruptUsage

VOID TMCT_Timer_Interrupt (INT vector)

Description

This function processes the actual hardware interrupt. Processing includes updating the systemclock and the countdown timer and the time-slice timer. If one or both of the timers expire, thetimer HISR is activated.

Functions Called

TMCT_Increment_Clock

TCCT_Activate_HISR

ESAL_GE_TMR_OS_TIMER_EOI


Component DescriptionsMailbox Component (MB)

December 15, 2006

Mailbox Component (MB)The mailbox component (MB) is responsible for processing all Nucleus PLUS mailboxfacilities. A Nucleus PLUS mailbox is a low overhead mechanism for inter-taskcommunication. Each mailbox is capable of holding one message. A mailbox message consistsof four 32-bit words. Tasks may suspend while waiting for a message from an empty mailbox.Conversely, tasks may suspend while trying to send to a mailbox that already contains amessage. Mailboxes are dynamically created and deleted by the user. See the Nucleus PLUSReference Manual for more detailed information about mailboxes.

Mailbox FilesThe MB consists of nine files. Each source file of the MB is defined in the following table.

Table 4-23. Mailbox Files

File Description

mb_defs.h This file contains constants and data structure definitions specific tothe MB.

mb_extr.h All external interfaces to the MB are defined in this file.

mbd.c Global data structures for the MB are defined in this file.

mbf_established.c These files contain the information gathering functions for the MB.

mbf_info.c

mbf_pointers.c

mbc_common.c This file contains all of the core functions of the MB. Functions thathandle basic send-to-mailbox and receive-from-mailbox services aredefined in this file.

mbs_broadcast.c These files contain supplemental functions of the MB. Functionscontained in these files are typically used less frequently than the corefunctions.mbs_reset.c

mbce_common.c These files contain the error checking function interfaces for the corefunctions defined in mbc_<function decription>.c.

mbse_broadcast.c These files contain the error checking function interfaces for thesupplemental functions defined in mbs_<function description>.c.

mbse_reset.c



Mailbox Data Structures

Created Mailbox List

Figure 4-11. MBD Created Mailboxes List

Nucleus PLUS mailboxes may be created and deleted dynamically. The mailbox control block(MCB) for each created mailbox is kept on a doubly linked, circular list. Newly createdmailboxes are placed at the end of the list, while deleted mailboxes are completely removedfrom the list. The head pointer of this list is MBD_Created_Mailboxes_List.

Created Mailbox List ProtectionNucleus PLUS protects the integrity of the Created Mailboxes List from competing tasks and/orHISRs. This is done by using an internal protection structure called MBD_List_ Protect. Allmailbox creation and deletion is done under the protection of MBD_List_Protect.

Field Declarations


Field Summary

Table 4-24.

Field Description





December 15, 2006

Total MailboxesThe total number of currently created Nucleus PLUS mailboxes is contained in the variableMBD_Total_Mailboxes. The content of this variable corresponds to the number of MCBs onthe created list. Manipulation of this variable is also done under the protection of MBD_List_Protect.

Mailbox Control BlockThe MCB MB_MCB contains the mailbox message area (four 32-bit unsigned words) and otherfields necessary for processing mailbox requests.

Field Declarations

CS_NODE mb_createdUNSIGNED mb_idCHAR mb_name[NU_MAX_NAME]DATA_ELEMENT mb_message_presentDATA_ELEMENT mb_fifo_suspendDATA_ELEMENT mb_padding[PAD_2]UNSIGNED mb_tasks_waitingUNSIGNED mb_message_area[MB_MESSAGE_SIZE]struct MB_SUSPEND_STRUCT *mb_suspension_list



Field Summary

Mailbox Suspension StructureTasks can suspend on empty and full mailbox conditions. During the suspension process aMB_SUSPEND structure is built. This structure contains information about the task and the task’smailbox request at the time of suspension. This suspension structure is linked onto the MCB ina doubly linked, circular list and is allocated off of the suspending task’s stack. There is onesuspension block for every task suspended on the mailbox.

Figure 4-12. Mailbox Suspension Structure

The order of the suspension block placement on the suspend list is determined at mailboxcreation. If a FIFO suspension was selected, the suspension block is added to the end of the list.

Table 4-25.

Field Description

mb_created This is the link node structure for mailboxes. It is linked into thecreated mailbox list, which is a doubly linked, circular list.

mb_id This holds the internal mailbox identification of 0x4D424F58, whichis an equivalent to ASCII MBOX.

mb_name This is the user-specified, 8 character name for the mailbox.

mb_message_present A flag that indicates if a message is present in the mailbox.

mb_fifo_suspend A flag that determines whether tasks suspend in FIFO or priorityorder.

mb_padding This is used to align the mailbox structure on an even boundary. Formost targets, this field is not used.

mb_tasks_waiting Indicates the number of tasks that are currently suspended on themailbox.

mb_message_area The storage area for the message.

*mb_suspension_list The head of the mailbox suspension list. If no tasks are suspended,this pointer is NULL.



December 15, 2006

Otherwise, if priority suspension was selected, the suspension block is placed after suspensionblocks for tasks of equal or higher priority.

Field Declarations

CS_NODE mb_suspend_linkMB_MCB *mb_mailboxTC_TCB *mb_suspended_taskUNSIGNED *mb_message_areaSTATUS mb_return_status

Field Summary

Mailbox FunctionsThe following sections provide a brief description of the functions in the MB. Review of theactual source code is recommended for further information.

Table 4-26.

Field Description

mb_suspend_link A link node structure for linking with other suspended blocks. It isused in a doubly linked circular suspension list.

*mb_mailbox A pointer to the mailbox structure.

*mb_suspended_task A pointer to the Task Control Block of the suspended task.

*mb_message_area A pointer indicating where the suspended task’s message buffer is.

mb_return_status The completion status of the task suspended on the mailbox.

Component DescriptionsMBC_Create_Mailbox


MBC_Create_MailboxUsage

STATUS MBC_Create_Mailbox (NU_MAILBOX *mailbox_ptr, CHAR *name, OPTIONsuspend_type)

Description

This function creates a mailbox and then places it on the list of created mailboxes.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsMBC_Delete_Mailbox

December 15, 2006

MBC_Delete_MailboxUsage

STATUS MBC_Delete_Mailbox (NU_MAILBOX *mailbox_ptr)

Description

This function deletes a mailbox and removes it from the list of created mailboxes. All taskssuspended on the mailbox are resumed. Note that this function does not free the memoryassociated with the mailbox control block. That is the responsibility of the application.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


Component DescriptionsMBC_Send_To_Mailbox


MBC_Send_To_MailboxUsage

STATUS MBC_Send_To_Mailbox (NU_MAILBOX *mailbox_ptr, VOID *message,UNSIGNED suspend)

Description

This function sends a 4-word message to the specified mailbox. If there are one or more taskssuspended on the mailbox for a message, the message is copied into the message area of the firsttask waiting and that task is resumed. If the mailbox is full, suspension of the calling task ispossible.

Functions Called

CSC_Place_On_List

CSC_Priority_Place_On_List



TCC_Resume_Task

TCC_Suspend_Task


Component DescriptionsMBC_Receive_From_Mailbox

December 15, 2006

MBC_Receive_From_MailboxUsage

STATUS MBC_Receive_From_Mailbox (NU_MAILBOX *mailbox_ptr, VOID*message,UNSIGNED suspend)

Description

This function receives a message from the specified mailbox. If there is a message currently inthe mailbox, the message is removed from the mailbox and placed in the caller’s area.Otherwise, if no message is present in the mailbox, suspension of the calling task is possible.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task

Component DescriptionsMBC_Cleanup


MBC_CleanupUsage

VOID MBC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from a mailbox. It is not calledunless a timeout or a task terminate is in progress. Note that protection (the same as atsuspension time) is already in effect.

Functions Called



Component DescriptionsMBCE_Create_Mailbox

December 15, 2006

MBCE_Create_MailboxUsage

STATUS MBCE_Create_Mailbox (NU_MAILBOX *mailbox_ptr, CHAR *name, OPTIONsuspend_type)

Description

This function performs error checking on the parameters supplied to the mailbox createfunction.

Functions Called

MBC_Create_Mailbox

Component DescriptionsMBCE_Delete_Mailbox


MBCE_Delete_MailboxUsage

STATUS MBCE_Delete_Mailbox (NU_MAILBOX *mailbox_ptr)

Description

This function performs error checking on the parameters supplied to the actual delete mailboxfunction.

Functions Called

MBC_Delete_Mailbox


Component DescriptionsMBCE_Send_To_Mailbox

December 15, 2006

MBCE_Send_To_MailboxUsage

STATUS MBCE_Send_To_Mailbox (NU_MAILBOX *mailbox_ptr, VOID *message,UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the send-to-mailboxfunction.

Functions Called

MBC_Sent_To_Mailbox

TCCE_Suspend_Error

Component DescriptionsMBCE_Receive_From_Mailbox


MBCE_Receive_From_MailboxUsage

STATUS MBCE_Receive_From_Mailbox (NU_MAILBOX *mailbox_ptr, VOID *message,UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the receive-from-mailboxfunction.

Functions Called

MBC_Receive_From_Mailbox

TCCE_Suspend_Error


Component DescriptionsMBF_Established_Mailboxes

December 15, 2006

MBF_Established_MailboxesUsage

UNSIGNED MBF_Established_Mailboxes (VOID)

Description

This function returns the current number of established mailboxes. Mailboxes previouslydeleted are no longer considered established.

Functions Called

TCCT_Check_Stack

Component DescriptionsMBF_Mailbox_Pointers


MBF_Mailbox_PointersUsage

UNSIGNED MBF_Mailbox_Pointers (NU_MAILBOX **pointer_list, UNSIGNEDmaximum_pointers)

Description

This function builds a list of mailbox pointers, starting at the specified location. The number ofmailbox pointers placed in the list is equivalent to the total number of mailboxes or themaximum number of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsMBF_Mailbox_Information

December 15, 2006

MBF_Mailbox_InformationUsage

STATUS MBF_Mailbox_Information (NU_MAILBOX *mailbox_ptr,CHAR *name, OPTION*suspend_type, DATA_ELEMENT *message_present,UNSIGNED *tasks_waiting,NU_TASK **first_task)

Description

This function returns information about the specified mailbox. However, if the suppliedmailbox pointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsMBS_Reset_Mailbox


MBS_Reset_MailboxUsage

STATUS MBS_Reset_Mailbox (NU_MAILBOX *mailbox_ptr)

Description

This function resets a mailbox back to the initial state. Any message in the mailbox isdiscarded. Also, all tasks suspended on the mailbox are resumed with the reset completionstatus.

Functions Called


TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsMBS_Broadcast_To_Mailbox

December 15, 2006

MBS_Broadcast_To_MailboxUsage

STATUS MBS_Broadcast_To_Mailbox (NU_MAILBOX *mailbox_ptr, VOID *message,UNSIGNED suspend)

Description

This function sends a message to all tasks currently waiting for a message from the mailbox. Ifno tasks are waiting, this service behaves like a normal send message function.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task

Component DescriptionsMBSE_Reset_Mailbox


MBSE_Reset_MailboxUsage

STATUS MBSE_Reset_Mailbox (NU_MAILBOX *mailbox_ptr)

Description

This function performs error checking on the parameters supplied to the actual reset mailboxfunction.

Functions Called

MBS_Reset_Mailbox


Component DescriptionsMBSE_Broadcast_To_Mailbox

December 15, 2006

MBSE_Broadcast_To_MailboxUsage

STATUS MBSE_Broadcast_To_Mailbox (NU_MAILBOX *mailbox_ptr, VOID*message,UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the mailbox broadcastfunction.

Functions Called

MBS_Broadcast_To_Mailbox

TCCE_Suspend_Error

Component DescriptionsQueue Component (QU)


Queue Component (QU)The queue component (QU) is responsible for processing all Nucleus PLUS queue facilities. ANucleus PLUS queue is a mechanism for tasks to communicate between each other. Eachqueue is capable of holding multiple messages. A queue message consists of one or more 32-bitwords. Tasks may suspend while waiting for a message from an empty queue. Conversely,tasks may suspend while trying to send to a queue that is in a full condition. You maydynamically create and delete the queues. See the Nucleus PLUS Reference Manual for moredetailed information about queues.

Queue FilesThe QU consists of nine files. Each source file of the QU is defined in the following table.

Table 4-27. Queue File Names

File Description

qu_defs.h This file contains constants and data structure definitions specific tothe QU.

qu_extr.h All external interfaces to the QU are defined in this file.

qud.c Global data structures for the QU are defined in this file.

quf_established.c These files contain the information gathering functions for the QU.

quf_info.c

quf_pointers.c

quc_common.c These files contain all of the core functions of the QU. Functions thathandle basic send-to-queue and receive-from-queue services aredefined in these files.quc_delete.c

qus_broadcast.c These files contain supplemental functions of the QU. Functionscontained in this file are typically used less frequently than the corefunctions.qus_front.c

qus_reset.c

quce_common.c These files contain the error checking function interfaces for the corefunctions defined in quc_<function description>.c.

quce_delete.c

quse_broadcast.c These files contain the error checking function interfaces for thesupplemental functions defined in qus_<function description>.c.

quse_front.c

quse_reset.c


Component DescriptionsQueue Component (QU)

December 15, 2006

Queue Data Structures

Created Queue List

Figure 4-13. QUD Created Queues List

Nucleus PLUS queues may be created and deleted dynamically. The queue control block(QCB) for each created queue is kept on a doubly linked, circular list. Newly created queues areplaced at the end of the list, while deleted queues are completely removed from the list. Thehead pointer of this list is QUD_Created_Queues_List.

Created Queue List ProtectionNucleus PLUS protects the integrity of the Created Queues List from competing tasks and/orHISRs. This is done by using an internal protection structure called QUD_List_Protect. Allqueue creation and deletion is done under the protection of QUD_List_Protect.

Field Declarations


Field Summary

Total QueuesThe total number of currently created Nucleus PLUS queues is contained in the variable QUD_Total_Queues. The content of this variable corresponds to the number of QCBs on the createdlist. Manipulation of this variable is also done under the protection of QUD_List_Protect.

Table 4-28.

Field Description



Component DescriptionsQueue Control Block


Queue Control BlockThe QCB QU_QCB contains the queue message area (one or more 32-bit unsigned words) andother fields necessary for processing queue requests.

Field Declarations

CS_NODE qu_createdUNSIGNED qu_idCHAR qu_name[NU_MAX_NAME]DATA_ELEMENT qu_fixed_sizeDATA_ELEMENT qu_fifo_suspendDATA_ELEMENT qu_paddingUNSIGNED qu_queue_sizeUNSIGNED qu_messagesUNSIGNED qu_message_sizeUNSIGNED qu_availableUNSIGNED_PTR qu_startUNSIGNED_PTR qu_endUNSIGNED_PTR qu_readUNSIGNED_PTR qu_writeUNSIGNED qu_tasks_waitingstruct QU_SUSPEND_STRUCT *qu_urgent_liststruct QU_SUSPEND_STRUCT *qu_suspension_list


Component DescriptionsQueue Suspension Structure

December 15, 2006

Field Summary

Queue Suspension StructureTasks can suspend on empty and full queue conditions. During the suspension process a QU_SUSPEND structure is built. This structure contains information about the task and the task’squeue request at the time of suspension. This suspension structure is linked onto the QCB in adoubly linked, circular list and is allocated off of the suspending task’s stack. There is onesuspension block for every task suspended on the queue.

Table 4-29.

Field Description

qu_created This is the link node structure for queues. It is linked into thecreated queues list, which is a doubly linked, circular list.

qu_id This holds the internal queue identification of 0x51554555, whichis equivalent to ASCII QUEU.

qu_name This is the user-specified, 8 character name for the queue.

qu_fixed_size A flag that indicates if the size of the queue is fixed or variable.

qu_fifo_suspend A flag that determines whether tasks suspend in FIFO or priorityorder.

qu_padding This is used to align the queue structure on an even boundary. Formost targets, this field is not used.

qu_queue_size This is the total size of the queue.

qu_messages A flag that indicates if there is a message present in the queue.

qu_message_size Holds the size of the queue message.

qu_available Indicates how many bytes are available in the queue.

qu_start Stores the beginning of the queue.

qu_end Stores the end of the queue.

qu_read This is the read pointer.

qu_write This is the write pointer.

qu_tasks_waiting Indicates the number of tasks that are currently suspended on thequeue.

*qu_urgent_list A pointer to the suspension list for urgent messages.

*qu_suspension_list The head pointer of the queue suspension list. If no tasks aresuspended, this pointer is NULL.

Component DescriptionsQueue Suspension Structure


Figure 4-14. Queue Suspension Structure

The order of the suspension block placement on the suspend list is determined at queue creation.If a FIFO suspension was selected, the suspension block is added to the end of the list.Otherwise, if priority suspension was selected, the suspension block is placed after suspensionblocks for tasks of equal or higher priority.

Field Declarations

QU_SUSPEND_STRUCTCS_NODE qu_suspend_linkQU_QCB *qu_queueTC_TCB *qu_suspended_taskUNSIGNED_PTR qu_message_areaUNSIGNED qu_message_sizeUNSIGNED qu_actual_sizeSTATUS qu_return_status

Field Summary

Queue FunctionsThe following sections provide a brief description of the functions in the QU. For furtherinformation, a review of the actual source code is recommended.

Table 4-30.

Field Description

qu_suspend_link A link node structure for linking with other suspended blocks. It isused in a doubly linked, circular suspension list.

*qu_queue A pointer to the queue structure.

*qu_suspended_task A pointer to the Task Control Block of the suspended task.

qu_message_area A pointer indicating where the suspended task’s message buffer is.

qu_message_size Stores the size of the requested message

qu_actual_size Stores the actual size of the message.

qu_return_status The completion status of the task suspended on the queue.


Component DescriptionsQUC_Create_Queue

December 15, 2006

QUC_Create_QueueUsage

STATUS QUC_Create_Queue (NU_QUEUE *queue_ptr, CHAR *name, VOID*start_address, UNSIGNED queue_size, OPTION message_type, UNSIGNEDmessage_size, OPTION suspend_type)

Description

This function creates a queue and then places it on the list of created queues.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsQUC_Delete_Queue


QUC_Delete_QueueUsage

STATUS QUC_Delete_Queue (NU_QUEUE *queue_ptr)

Description

This function deletes a queue and removes it from the list of created queues. All taskssuspended on the queue are resumed. Note that this function does not free the memoryassociated with the queue. That is the responsibility of the application.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]



Component DescriptionsQUC_Send_To_Queue

December 15, 2006

QUC_Send_To_QueueUsage

STATUS QUC_Send_To_Queue (NU_QUEUE *queue_ptr, VOID *message, UNSIGNEDsize, UNSIGNED suspend)

Description

This function sends a message to the specified queue. The caller determines the messagelength. If there are one or more tasks suspended on the queue for a message, the message iscopied into the message area of the first waiting task. If the task’s request is satisfied, it isresumed. Otherwise, if the queue cannot hold the message, suspension of the calling task is anoption of the caller.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task

Component DescriptionsQUC_Receive_From_Queue


QUC_Receive_From_QueueUsage

STATUS QUC_Receive_From_Queue (NU_QUEUE *queue_ptr, VOID *message,UNSIGNED size, UNSIGNED *actual_size,UNSIGNED suspend)

Description

This function receives a message from the specified queue. The caller specifies the size of themessage. If there is a message currently in the queue, the message is removed from the queueand placed in the caller’s area. Suspension is possible if the request cannot be satisfied.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task


Component DescriptionsQUC_Cleanup

December 15, 2006

QUC_CleanupUsage

VOID QUC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from a queue. It is not calledunless a timeout or a task terminate is in progress. Note that protection (the same as atsuspension time) is already in effect.

Functions Called


Component DescriptionsQUCE_Create_Queue


QUCE_Create_QueueUsage

STATUS QUCE_Create_Queue (NU_QUEUE *queue_ptr, CHAR *name, VOID*start_address, UNSIGNED queue_size, OPTION message_type, UNSIGNEDmessage_size, OPTION suspend_type)

Description

This function performs error checking on the parameters supplied to the queue create function.

Functions Called

QUC_Create_Queue


Component DescriptionsQUCE_Delete_Queue

December 15, 2006

QUCE_Delete_QueueUsage

STATUS QUCE_Delete_Queue (NU_QUEUE *queue_ptr)

Description

This function performs error checking on the parameter supplied to the queue delete function.

Functions Called

QUC_Delete_Queue

Component DescriptionsQUCE_Send_To_Queue


QUCE_Send_To_QueueUsage

STATUS QUCE_Send_To_Queue (NU_QUEUE *queue_ptr, VOID *message, UNSIGNEDsize, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the send message to queuefunction.

Functions Called

QUC_Send_To_Queue

TCCE_Suspend_Error


Component DescriptionsQUCE_Receive_From_Queue

December 15, 2006

QUCE_Receive_From_QueueUsage

STATUS QUCE_Receive_From_Queue (NU_QUEUE *queue_ptr, VOID *message,UNSIGNED size, UNSIGNED *actual_size, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the receive message fromqueue function.

Functions Called

QUC_Receive_From_Queue

TCCE_Suspend_Error

Component DescriptionsQUF_Established_Queues


QUF_Established_QueuesUsage

UNSIGNED QUF_Established_Queues (VOID)

Description

This function returns the current number of established queues. Queues previously deleted areno longer considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsQUF_Queue_Information

December 15, 2006

QUF_Queue_InformationUsage

STATUS QUF_Queue_Information (NU_QUEUE*queue_ptr, CHAR *name, VOID**start_address, UNSIGNED*queue_size, UNSIGNED *available, UNSIGNED*messages, OPTION *message_type, UNSIGNED *message_size, OPTION*suspend_type, UNSIGNED *tasks_waiting, NU_TASK **first_task)

Description

This function returns information about the specified queue. However, if the supplied queuepointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsQUF_Queue_Pointers


QUF_Queue_PointersUsage

UNSIGNED QUF_Queue_Pointers (NU_QUEUE **pointer_list, UNSIGNEDmaximum_pointers)

Description

This function builds a list of queue pointers, starting at the specified location. The number ofqueue pointers placed in the list is equivalent to the total number of queues or the maximumnumber of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsQUS_Reset_Queue

December 15, 2006

QUS_Reset_QueueUsage

STATUS QUS_Reset_Queue (NU_QUEUE *queue_ptr)

Description

This function resets the specified queue back to the original state. Any messages in the queueare discarded. Also, any tasks currently suspended on the queue are resumed with the resetstatus.

Functions Called


TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsQUS_Send_To_Front_Of_Queue


QUS_Send_To_Front_Of_QueueUsage

STATUS QUS_Send_To_Front_Of_Queue (NU_QUEUE *queue_ptr, VOID *message,UNSIGNED size, UNSIGNED suspend)

Description

This function sends a message to the front of the specified message queue. The callerdetermines the message length. If there are any tasks suspended on the queue for a message, themessage is copied into the message area of the first waiting task and that task is resumed. Ifthere is enough room in the queue, the message is copied in front of all other messages. If thereis not enough room in the queue, suspension of the caller is possible.

Functions Called

CSC_Place_On_List



TCC_Resume_Task

TCC_Suspend_Task

[TCCT_Check_Stack]


Component DescriptionsQUS_Broadcast_To_Queue

December 15, 2006

QUS_Broadcast_To_QueueUsage

STATUS QUS_Broadcast_To_Queue (NU_QUEUE *queue_ptr, VOID *message,UNSIGNED size, UNSIGNED suspend)

Description

This function sends a message to all tasks waiting for a message from the specified queue. Ifthere are no tasks waiting for a message, the service performs like a standard send request.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task

Component DescriptionsQUSE_Reset_Queue


QUSE_Reset_QueueUsage

STATUS QUSE_Reset_Queue (NU_QUEUE *queue_ptr)

Description

This function performs error checking on the parameter supplied to the queue reset function.

Functions Called

QUS_Reset_Queue


Component DescriptionsQUSE_Send_To_Front_Of_Queue

December 15, 2006

QUSE_Send_To_Front_Of_QueueUsage

STATUS QUSE_Send_To_Front_Of_Queue (NU_QUEUE *queue_ptr, UNSIGNED size,UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the send message to frontof queue function.

Functions Called

QUS_Send_To_Front_Of_Queue

TCCE_Suspend_Error

Component DescriptionsQUSE_Broadcast_To_Queue


QUSE_Broadcast_To_QueueUsage

STATUS QUSE_Broadcast_To_Queue (NU_QUEUE *queue_ptr, VOID *message,UNSIGNED size, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the broadcast message toqueue function.

Functions Called

QUS_Broadcast_To_Queue

TCCE_Suspend_Error


Component DescriptionsPipe Component (PI)

December 15, 2006

Pipe Component (PI)The pipe component (PI) is responsible for processing all Nucleus PLUS pipe facilities. ANucleus PLUS pipe is a mechanism for tasks to communicate between each other. Each pipe iscapable of holding multiple messages. A pipe message consists of one or more bytes. Tasksmay suspend while waiting for a message from an empty pipe. Conversely, tasks may suspendwhile trying to send to a pipe that is in a full condition. You can dynamically create and deletethe pipes. See the Nucleus PLUS Reference Manual for more detailed information about pipes.

Pipe FilesThe PI consists of nine files. Each source file of the PI is defined in the following table.

Table 4-31. Pipe File Names

File Description

pi_defs.h This file contains constants and data structure definitionsspecific to the PI.

pi_extr.h All external interfaces to the PI are defined in this file.

pid.c Global data structures for the PI are defined in this file.

pif_established.c These files contain the information gathering functions for thePI.

pif_info.c

pif_pointers.c

pic_common.c This file contains all of the core functions of the PI. Functionsthat handle basic send-to-pipe and receive-from-pipe servicesare defined in this file.

pis_boadcast.c These files contain supplemental functions of the PI. Functionscontained in this file are typically used less frequently than thecore functions.pis_front.c

pis_reset.c

pice_common.c This file contains the error checking function interfaces for thecore functions defined in pic_<function description>.c.

pise_broadcast.c These files contain the error checking function interfaces for thesupplemental functions defined in pis_<functiondescription>.c.pise_front.c

pise_reset.c



Pipe Data Structures

Created Pipe List

Figure 4-15. PID Created Pipes List

Nucleus PLUS pipes may be created and deleted dynamically. The pipe control block (PCB)for each created pipe is kept on a doubly linked, circular list. Newly created pipes are placed atthe end of the list, while deleted pipes are completely removed from the list. The head pointerof this list is PID_Created_Pipes_List.

Created Pipe List ProtectionNucleus PLUS protects the integrity of the Created Pipes List from competing tasks and/orHISRs. This is done by using an internal protection structure called PID_List_ Protect. All pipecreation and deletion is done under the protection of PID_List_ Protect.

Field Declarations


Field Summary

Total PipesThe total number of currently created Nucleus PLUS pipes is contained in the variable PID_Total_Pipes. The contents of this variable correspond to the number of PCBs on the created list.Manipulation of this variable is also done under the protection of PID_List_Protect.

Table 4-32.

Field Description





December 15, 2006

Pipe Control BlockThe PCB PI_PCB contains the pipe message area (one or more bytes) and other fields necessaryfor processing pipe requests.

Field Declarations

CS_NODE pi_createdUNSIGNED pi_idCHAR pi_name[NU_MAX_NAME]DATA_ELEMENT pi_fixed_sizeDATA_ELEMENT pi_fifo_suspendDATA_ELEMENT pi_padding[PAD_2]UNSIGNED pi_pipe_sizeUNSIGNED pi_message_sizeUNSIGNED pi_availableBYTE_PTR pi_startBYTE_PTR pi_endBYTE_PTR pi_readBYTE_PTR pi_writeUNSIGNED pi_tasks_waitingUNSIGNED pi_messagesstruct PI_SUSPEND_STRUCT *pi_urgent_liststruct PI_SUSPEND_STRUCT *pi_suspension_list



Field Summary

Pipe Suspension Structure

Tasks can suspend on empty and full pipe conditions. During the suspension process a PI_SUSPEND structure is built. This structure contains information about the task and the task’spipe request at the time of suspension. This suspension structure is linked onto the PCB in adoubly linked, circular list and is allocated off of the suspending task’s stack. There is onesuspension block for every task suspended on the pipe.

Table 4-33.

Field Description

pi_create This is the link node structure for pipes. It is linked into thecreated pipes list, which is a doubly linked, circular list.

pi_id This holds the internal pipe identification of 0x50495045,which is equivalent to ASCII PIPE.

pi_name This is the user-specified, 8 character name for the pipe.

pi_fixed_size A flag that indicates if the size of the pipe is fixed or variable.

pi_fifo_suspend A flag that determines whether tasks suspend in FIFO orpriority order.

pi_padding This is used to align the pipe structure on an even boundary.For most targets, this field is not used.

pi_pipe_size This is the total size of the pipe.

pi_messages A flag that indicates if there is a message present in the pipe.

pi_message_size Holds the size of the message.

pi_available Indicates how many bytes are available in the pipe.

pi_start Stores the beginning of the pipe.

pi_end Stores the end of the pipe.

pi_read This is the read pointer.

pi_write This is the write pointer.

pi_tasks_waiting Indicates the number of tasks that are currently suspended onthe pipe.

*pi_urgent_list A pointer to the suspension list for urgent messages.

*pi_suspension_list The head pointer of the pipe suspension list. If no tasks aresuspended, this pointer is NULL.



December 15, 2006

Figure 4-16. Pipe Suspension Structure

The order of the suspension block placement on the suspend list is determined at pipe creation.If a FIFO suspension was selected, the suspension block is added to the end of the list.Otherwise, if priority suspension was selected, the suspension block is placed after suspensionblocks for tasks of equal or higher priority.

Field Declarations

CS_NODE pi_suspend_linkPI_PCB *pi_pipeTC_TCB *pi_suspended_taskBYTE_PTR pi_message_areaUNSIGNED pi_message_sizeUNSIGNED pi_actual_sizeSTATUS pi_return_status

Field Summary

Pipe FunctionsThe following sections provide a brief description of the functions in the PI. For furtherinformation, a review of the actual source code is recommended.

Table 4-34.

Field Description

pi_suspend_link A link node structure for linking with other suspended blocks. Itis used in a doubly linked, circular suspension list.

*pi_pipe A pointer to the pipe structure.

*pi_suspended_task A pointer to the Task Control Block of the suspended task.

pi_message_area A pointer indicating where the suspended task’s message bufferis.

pi_message_size Stores the size of the requested message

pi_actual_size Stores the actual size of the message.

pi_return_status The completion status of the task suspended on the pipe.

Component DescriptionsPIC_Create_Pipe


PIC_Create_PipeUsage

STATUS PIC_Create_Pipe (NU_PIPE *pipe_ptr, CHAR *name, VOID *start_address,UNSIGNED pipe_size, OPTION message_type, UNSIGNED message_size, OPTIONsuspend_type)

Description

This function creates a pipe and then places it on the list of created pipes.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsPIC_Delete_Pipe

December 15, 2006

PIC_Delete_PipeUsage

STATUS PIC_Delete_Pipe (NU_PIPE *pipe_ptr)

Description

This function deletes a pipe and removes it from the list of created pipes. All tasks suspendedon the pipe are resumed. Note that this function does not free the memory associated with thepipe. That is the responsibility of the application.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


Component DescriptionsPIC_Send_To_Pipe


PIC_Send_To_PipeUsage

STATUS PIC_Send_To_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNED size,UNSIGNED suspend)

Description

This function sends a message to the specified pipe. The caller determines the message length.If there are one or more tasks suspended on the pipe for a message, the message is copied intothe message area of the first waiting task. If the task’s request is satisfied, it is resumed.Otherwise, if the pipe cannot hold the message, suspension of the calling task is an option of thecaller.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task


Component DescriptionsPIC_Receive_From_Pipe

December 15, 2006

PIC_Receive_From_PipeUsage

STATUS PIC_Receive_From_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNED size,UNSIGNED *actual_size, UNSIGNED suspend)

Description

This function receives a message from the specified pipe. The caller specifies the size of themessage. If there is a message currently in the pipe, the message is removed from the pipe andplaced in the caller’s area. Suspension is possible if the request cannot be satisfied.

Functions Called

CSC_Place_On_List



TCC_Resume_Task

TCC_Suspend_Task

TCC_Task_Priority

TCCT_Check_Stack]


TCCT_Current_Thread

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsPIC_Cleanup


PIC_CleanupUsage

VOID PIC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from a pipe. It is not called unlessa timeout or a task terminate is in progress. Note that protection (the same as at suspensiontime) is already in effect.

Functions Called



Component DescriptionsPICE_Create_Pipe

December 15, 2006

PICE_Create_PipeUsage

STATUS PICE_Create_Pipe (NU_PIPE *pipe_ptr, CHAR *name,VOID *start_address,UNSIGNED pipe_size, OPTION message_type, UNSIGNED message_size, OPTIONsuspend_type)

Description

This function performs error checking on the parameters supplied to the pipe create function.

Functions Called

PIC_Create_Pipe

Component DescriptionsPICE_Delete_Pipe


PICE_Delete_PipeUsage

STATUS PICE_Delete_Pipe (NU_PIPE *pipe_ptr)

Description

This function performs error checking on the parameter supplied to the pipe delete function.

Functions Called

PIC_Delete_Pipe


Component DescriptionsPICE_Send_To_Pipe

December 15, 2006

PICE_Send_To_PipeUsage

STATUS PICE_Send_To_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNED size,UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the send message to pipefunction.

Functions Called

PIC_Send_To_Pipe

TCCE_Suspend_Error

Component DescriptionsPICE_Receive_From_Pipe


PICE_Receive_From_PipeUsage

STATUS PICE_Receive_From_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNED size,UNSIGNED *actual_size, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the receive message frompipe function.

Functions Called

PIC_Receive_From_Pipe

TCCE_Suspend_Error


Component DescriptionsPIF_Established_Pipes

December 15, 2006

PIF_Established_PipesUsage

UNSIGNED PIF_Established_Pipes (VOID)

Description

This function returns the current number of established pipes. Pipes previously deleted are nolonger considered established.

Functions Called

[TCCT_Check_Stack]

Component DescriptionsPIF_Pipe_Information


PIF_Pipe_InformationUsage

STATUS PIF_Pipe_Information (NU_PIPE *pipe_ptr, CHAR *name, VOID start_address,UNSIGNED *pipe_size, UNSIGNED *available, UNSIGNED *messages, OPTION*message_type, UNSIGNED *message_size, OPTION *suspend_type, UNSIGNED*tasks_waiting, NU_TASK **first_task)

Description

This function returns information about the specified pipe. However, if the supplied pipe pointeris invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsPIF_Pipe_Pointers

December 15, 2006

PIF_Pipe_PointersUsage

UNSIGNED PIF_Pipe_Pointers (NU_PIPE **pointer_list, UNSIGNED maximum_pointers)

Description

This function builds a list of pipe pointers, starting at the specified location. The number of pipepointers placed in the list is equivalent to the total number of pipes or the maximum number ofpointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsPIS_Reset_Pipe


PIS_Reset_PipeUsage

STATUS PIS_Reset_Pipe (NU_PIPE *pipe_ptr)

Description

This function resets the specified pipe back to the original state. Any messages in the pipe arediscarded. Also, any tasks currently suspended on the pipe are resumed with the reset status.

Functions Called


TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsPIS_Send_To_Front_Of_Pipe

December 15, 2006

PIS_Send_To_Front_Of_PipeUsage

STATUS PIS_Send_To_Front_Of_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNEDsize, UNSIGNED suspend)

Description

This function sends a message to the front of the specified message pipe. The caller determinesthe message length. If there are any tasks suspended on the pipe for a message, the message iscopied into the message area of the first waiting task and that task is resumed. If there is enoughroom in the pipe, the message is copied in front of all other messages. If there is not enoughroom in the pipe, suspension of the caller is possible.

Functions Called

CSC_Place_On_List



TCC_Resume_Task

TCC_Suspend_Task

Component DescriptionsPIS_Broadcast_To_Pipe


PIS_Broadcast_To_PipeUsage

STATUS PIS_Broadcast_To_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNED size,UNSIGNED suspend)

Description

This function sends a message to all tasks waiting for a message from the specified pipe. Ifthere are no tasks waiting for a message, the service performs like a standard send request.

Functions Called

CSC_Place_On_List




TCC_Resume_Task

TCC_Suspend_Task


Component DescriptionsPISE_Reset_Pipe

December 15, 2006

PISE_Reset_PipeUsage

STATUS PISE_Reset_Pipe (NU_PIPE *pipe_ptr)

Description

This function performs error checking on the parameter supplied to the pipe reset function.

Functions Called

PIS_Reset_Pipe

Component DescriptionsPISE_Send_To_Front_Of_Pipe


PISE_Send_To_Front_Of_PipeUsage

STATUS PISE_Send_To_Front_Of_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNEDsize, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the send message to frontof pipe function.

Functions Called

PIS_Send_To_Front_Of_Pipe

TCCE_Suspend_Error


Component DescriptionsPISE_Broadcast_To_Pipe

December 15, 2006

PISE_Broadcast_To_PipeUsage

STATUS PISE_Broadcast_To_Pipe (NU_PIPE *pipe_ptr, VOID *message, UNSIGNED size,UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the broadcast message topipe function.

Functions Called

PIS_Broadcast_To_Pipe

TCCE_Suspend_Error

Component DescriptionsSemaphore Component (SM)


Semaphore Component (SM)The semaphore component (SM) is responsible for processing all Nucleus PLUS semaphorefacilities. A Nucleus PLUS semaphore is a mechanism to synchronize the execution of varioustasks in an application. Nucleus PLUS provides counting semaphores that range in value from0 to 4,294,967,294. Tasks may suspend while waiting for a non-zero semaphore value. You candynamically create and delete semaphores. See the Nucleus PLUS Reference Manual for moredetailed information about semaphores.

Semaphore FilesThe SM consists of nine files. Each source file of the SM is defined in the following table.

Table 4-35. Semaphore File Names

File Description

sm_defs.h This file contains constants and data structure definitions specific tothe SM.

sm_extr.h All external interfaces to the SM are defined in this file.

smd.c Global data structures for the SM are defined in this file.

smf_established.c These files contain the information gathering functions for the SM.

smf_info.c

smf_pointers.c

smc_common.c These files contain all of the core functions of the SM. Functions thathandle basic obtain-semaphore and release-semaphore services aredefined in these files.smc_delete.c

sms_reset.c These files contain supplemental functions of the SM. Functionscontained in this file are typically used less frequently than the corefunctions.

smce_common.c These files contain the error checking function interfaces for the corefunctions defined in smc_<function description>.c.

smce_delete.c

smse_reset.c These files contain the error checking function interfaces for thesupplemental functions defined in sms_<function description>.c.



December 15, 2006

Semaphore Data Structures

Created Semaphore List

Figure 4-17. SMD Created Semaphores List

Nucleus PLUS semaphores may be created and deleted dynamically. The semaphore controlblock (SCB) for each created semaphore is kept on a doubly linked, circular list. Newly createdsemaphores are placed at the end of the list, while deleted semaphores are completely removedfrom the list. The head pointer of this list is SMD_Created_Semaphores_List.

Created Semaphore List ProtectionNucleus PLUS protects the integrity of the Created Semaphores List from competing tasksand/or HISRs. This is done by using an internal protection structure called SMD_ List_Protect.All semaphore creation and deletion is done under the protection of SMD_List_Protect.

Field Declarations


Field Summary

Table 4-36.

Field Description


tc_thread_waiting A flag indicating that one or more threads are waiting for theprotection



Total SemaphoresThe total number of currently created Nucleus PLUS semaphores is contained in the variableSMD_Total_Semaphores. The contents of this variable correspond to the number of SCBs onthe created list. Manipulation of this variable is also done under the protection ofSMD_List_Protect.

Semaphore Control BlockThe Semaphores Control Block SM_SCB contains the semaphore count and other fieldsnecessary for processing semaphore requests.

Field Declarations

CS_NODE sm_createdUNSIGNED sm_idCHAR sm_name[NU_MAX_NAME]UNSIGNED sm_semaphore_countDATA_ELEMENT sm_fifo_suspendDATA_ELEMENT sm_padding[PAD_1]UNSIGNED sm_tasks_waitingstruct SM_SUSPEND_STRUCT *sm_suspension_list



December 15, 2006

Field Summary

Semaphore Suspension StructureTasks can suspend on a semaphore whose current count is zero. During the suspension process,a SM_SUSPEND_STRUCT structure is built. This structure contains information about thetask and the task’s semaphore request at the time of suspension. This suspension structure islinked onto the SCB in a doubly linked, circular list and is allocated from the suspending task’sstack. There is one suspension block for every task suspended on the semaphore.

Figure 4-18. Semaphore Suspension Structure

The order of the suspension block placement on the suspend list is determined at semaphorecreation. If a FIFO suspension was selected, the suspension block is added to the end of the list.Otherwise, if priority suspension was selected, the suspension block is placed after suspensionblocks for tasks of equal or higher priority.

Table 4-37.

Field Description

sm_created This is the link node structure for semaphores. It is linked into thecreated semaphores list, which is a doubly linked, circular list.

sm_id This holds the internal semaphore identification of 0x53454D41,which is equivalent to ASCII SEMA.

sm_name This is the user-specified, 8 character name for the semaphore.

sm_semaphore_count Stores the current count of the semaphore.

sm_fifo_suspend A flag that determines whether tasks suspend in FIFO or priorityorder.

sm_padding This is used to align the semaphore structure on an evenboundary. For most targets, this field is not used.

sm_tasks_waiting Indicates the number of tasks that are currently suspended on thesemaphore.

*sm_suspension_list The head pointer of the semaphore suspension list. If no tasks aresuspended, this pointer is NULL.



Field Declarations

CS_NODE sm_suspend_linkSM_SCB *sm_semaphoreTC_TCB *sm_suspended_taskSTATUS sm_return_status

Field Summary

Semaphore FunctionsThe following sections provide a brief description of the functions in the SM. For furtherinformation, a review of the actual source code is recommended.

Table 4-38.

Field Description

sm_suspend_link A link node structure for linking with other suspended blocks. It isused in a doubly linked, circular suspension list.

*sm_semaphore A pointer to the semaphore structure.

*sm_suspended_task A pointer to the Task Control Block of the suspended task.

sm_return_status The completion status of the task suspended on the semaphore


Component DescriptionsSMC_Create_Semaphore

December 15, 2006

SMC_Create_SemaphoreUsage

STATUS SMC_Create_Semaphore (NU_SEMAPHORE *semaphore_ptr, CHAR *name,UNSIGNED initial_count, OPTION suspend_type)

Description

This function creates a semaphore and places it on the list of created semaphores.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsSMC_Delete_Semaphore


SMC_Delete_SemaphoreUsage

STATUS SMC_Delete_Semaphore (NU_SEMAPHORE *semaphore_ptr)

Description

This function deletes a semaphore and removes it from the list of created semaphores. All taskssuspended on the semaphore are resumed. Note that this function does not free the memoryassociated with the semaphore control block. That is the responsibility of the application.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]



Component DescriptionsSMC_Obtain_Semaphore

December 15, 2006

SMC_Obtain_SemaphoreUsage

STATUS SMC_Obtain_Semaphore (NU_SEMAPHORE *semaphore_ptr, UNSIGNEDsuspend)

Description

This function obtains an instance of the semaphore. An instance corresponds to decrementingthe counter by one. If the counter is greater than zero at the time of this call, this function can becompleted immediately. Otherwise, suspension is possible.

Functions Called

CSC_Place_On_List



TCC_Suspend_Task

TCC_Task_Priority

[TCCT_Check_Stack]

TCCT_Current_Thread

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsSMC_Release_Semaphore


SMC_Release_SemaphoreUsage

STATUS SMC_Release_Semaphore (NU_SEMAPHORE *semaphore_ptr)

Description

This function releases a previously obtained semaphore. If one or more tasks are waiting, thefirst task is given the released instance of the semaphore. Otherwise, the semaphore instancecounter is simply incremented.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsSMC_Cleanup

December 15, 2006

SMC_CleanupUsage

VOID SMC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from a semaphore. It is not calledunless a timeout or a task terminate is in progress. Note that protection (the same as atsuspension time) is already in effect.

Functions Called


Component DescriptionsSMCE_Create_Semaphore


SMCE_Create_SemaphoreUsage

STATUS SMCE_Create_Semaphore (NU_SEMAPHORE *semaphore_ptr, CHAR *name,UNSIGNED initial_count, OPTION suspend_type)

Description

This function performs error checking on the parameters supplied to the create semaphorefunction.

Functions Called

SMC_Create_Semaphore


Component DescriptionsSMCE_Delete_Semaphore

December 15, 2006

SMCE_Delete_SemaphoreUsage

STATUS SMCE_Delete_Semaphore (NU_SEMAPHORE *semaphore_ptr)

Description

This function performs error checking on the parameters supplied to the delete semaphorefunction.

Functions Called

SMC_Delete_Semaphore

Component DescriptionsSMCE_Obtain_Semaphore


SMCE_Obtain_SemaphoreUsage

STATUS SMCE_Obtain_Semaphore (NU_SEMAPHORE *semaphore_ptr, UNSIGNEDsuspend)

Description

This function performs error checking on the parameters supplied to the obtain semaphorefunction.

Functions Called

SMC_Obtain_Semaphore

TCCE_Suspend_Error


Component DescriptionsSMCE_Release_Semaphore

December 15, 2006

SMCE_Release_SemaphoreUsage

STATUS SMCE_Release_Semaphore (NU_SEMAPHORE *semaphore_ptr)

Description

This function performs error checking on the parameters supplied to the release semaphorefunction.

Functions Called

SMC_Release_Semaphore

Component DescriptionsSMF_Established_Semaphores


SMF_Established_SemaphoresUsage

UNSIGNED SMF_Established_Semaphores (VOID)

Description

This function returns the current number of established semaphores. Semaphores previouslydeleted are no longer considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsSMF_Semaphore_Pointers

December 15, 2006

SMF_Semaphore_PointersUsage

UNSIGNED SMF_Semaphore_Pointers (NU_SEMAPHORE **pointer_list, UNSIGNEDmaximum_pointers)

Description

This function builds a list of semaphore pointers, starting at the specified location. The numberof semaphore pointers placed in the list is equivalent to the total number of semaphores or themaximum number of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsSMF_Semaphore_Information


SMF_Semaphore_InformationUsage

STATUS SMF_Semaphore_Information (NU_SEMAPHORE *semaphore_ptr, CHAR *name,UNSIGNED*current_count, OPTION *suspend_type, UNSIGNED tasks_waiting,NU_TASK **first_task)

Description

This function returns information about the specified semaphore. However, if the suppliedsemaphore pointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsSMS_Reset_Semaphore

December 15, 2006

SMS_Reset_SemaphoreUsage

STATUS SMS_Reset_Semaphore (NU_SEMAPHORE *semaphore_ptr, UNSIGNEDinitial_count)

Description

This function resets a semaphore back to the initial state. All tasks suspended on the semaphoreare resumed with the reset completion status.

Functions Called


TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsSMSE_Reset_Semaphore


SMSE_Reset_SemaphoreUsage

STATUS SMSE_Reset_Semaphore (NU_SEMAPHORE *semaphore_ptr, UNSIGNEDinitial_count)

Description

This function performs error checking on the parameters supplied to the reset semaphorefunction.

Functions Called

SMS_Reset_Semaphore


Component DescriptionsEvent Group Component (EV)

December 15, 2006

Event Group Component (EV)The event group component (EV) is responsible for processing all Nucleus PLUS event groupfacilities. A Nucleus PLUS event is a mechanism to indicate that a certain system event hasoccurred. An event is represented by a single bit in an event group. This bit is called an eventflag. There are 32 event flags in each event group. Tasks may suspend while waiting for aparticular set of event flags. You can dynamically create and delete event groups. See theNucleus PLUS Reference Manual for more detailed information about events.

Event Group FilesThe EV consists of seven files. Each source file of the Event Group Component is defined inthe following table.

Table 4-39. Event Group File Names

File Description

ev_defs.h This file contains constants and data structure definitions specific to theEV.

ev_extr.h All external interfaces to the EV are defined in this file.

evd.c Global data structures for the EV are defined in this file.

evf_established.c These files contain the information gathering functions for the EV.

evf_info.c

evf_pointers.c

evc_common.c These files contain all of the core functions of the EV. Functions thathandle basic set-event and retrieve-event services are defined in thesefiles.evc_delete.c

evce_common.c These files contain the error checking function interfaces for the corefunctions defined in evc_<function description>.c.

evce_delete.c



Event Group Data Structures

Created Event Group List

Figure 4-19. EVD Created Events Group List

Nucleus PLUS events may be created and deleted dynamically. The event group control block(GCB) for each created event group is kept on a doubly linked, circular list. Newly createdevent groups are placed at the end of the list, while deleted event groups are completelyremoved from the list. The head pointer of this list is EVD_Created_ Events_Group_List.

Created Event Group List ProtectionNucleus PLUS protects the integrity of the Created Events Group List from competing tasksand/or HISRs. This is done by using an internal protection structure called EVD_ List_Protect.All event group creation and deletion is done under the protection of EVD_List_Protect.


Functions Called

Total Event GroupsThe total number of currently created Nucleus PLUS event groups is contained in the variableEVD_Total_Event_Groups. The contents of this variable correspond to the number of GCBson the created list. Manipulation of this variable is also done under the protection of EVD_List_Protect.

Table 4-40.

Field Description


tc_thread_waiting A flag indicating that one or more threads are waiting for protection



December 15, 2006

Event Group Control BlockThe GCB EV_GCB contains the current event flags and other fields necessary for processingevent requests.

Field Declarations

CS_NODE ev_createdUNSIGNED ev_idCHAR ev_name[NU_MAX_NAME]UNSIGNED ev_current_eventsUNSIGNED ev_tasks_waitingstruct EV_SUSPEND_STRUCT *ev_suspension_list

Field Summary

Event Group Suspension Structure

Figure 4-20. Event Group Suspension Structure

Table 4-41.

Field Description

ev_created This is the link node structure for events. It is linked into thecreated events group list, which is a doubly linked, circular list.

ev_id This holds the internal event group identification of0x45564E54, which is equivalent to ASCII EVNT.

ev_name This is the user-specified, 8 character name for the eventgroup.

ev_current_event Contains the current event flags.

ev_tasks_waiting Indicates the number of tasks that are currently suspended onan event group.

*ev_suspension_list The head pointer of the event group suspension list. If no tasksare suspended, this pointer is NULL.



Tasks can suspend when an event group does not match the user specified combination of eventflags. During the suspension process the EV_SUSPEND_STRUCT structure is built. Thisstructure contains information about the task and the task’s event group request at the time ofsuspension. This suspension structure is linked onto the GCB in a doubly linked, circular listand is allocated off of the suspending task’s stack. There is one suspension block for every tasksuspended on the event group.

Field Declarations

CS_NODE ev_suspend_linkEV_GCB *ev_event_groupUNSIGNED ev_requested_eventsDATA_ELEMENT ev_operationDATA_ELEMENT ev_padding[PAD_1]TC_TCB *ev_suspended_taskSTATUS ev_return_statusUNSIGNED ev_actual_events

Field Summary

Event Group FunctionsThe following sections provide a brief description of the functions in the EV. Review of theactual source code is recommended for further information.

Table 4-42.

Field Description

ev_suspend_link A link node structure for linking with other suspended blocks.It is used in a doubly-linked circular suspension list

*em_event_group A pointer to the event group structure.

ev_requested_events The event group that has been requested.

ev_operations The type of operation that is requested on the event group. Thisis typically some sort of AND/OR combination.

ev_padding This is used to align the suspend event group structure on aneven boundary. For most targets, this field is not used.

*ev_suspeneded_task A pointer to the Task Control Block of the suspended task.

ev_return_status The completion status of the task suspended on the event group.

ev_actual_events The set of actual event flags returned by the request.


Component DescriptionsEVC_Create_Event_Group

December 15, 2006

EVC_Create_Event_GroupUsage

STATUS EVC_Create_Event_Group (NU_EVENT_GROUP *event_group_ptr, CHAR*name)

Description

This function creates an event group and then places it on the list of created event groups.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsEVC_Delete_Event_Group


EVC_Delete_Event_GroupUsage

STATUS EVC_Delete_Event_Group (NU_EVENT_GROUP *event_group_ptr)

Description

This function deletes an event group and removes it from the list of created event groups. Alltasks suspended on the event group are resumed. Note that this function does not free thememory associated with the event group control block. That is the responsibility of theapplication.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_Protect

TCCT_Set_Current_ProtectTCCT_System_Protect


TCCT_Unprotect


Component DescriptionsEVC_Set_Events

December 15, 2006

EVC_Set_EventsUsage

STATUS EVC_Set_Events (NU_EVENT_GROUP *event_group_ptr, UNSIGNED events,OPTION operation)

Description

This function sets event flags within the specified event flag group. Event flags may be ANDedor ORed against the current events of the group. Tasks suspended on a group are resumed whenthe requested event is satisfied.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsEVC_Retrieve_Events


EVC_Retrieve_EventsUsage

STATUS EVC_Retrieve_Events (NU_EVENT_GROUP *event_group_ptr, UNSIGNEDrequested_events, OPTION operation, UNSIGNED *retrieved_events, UNSIGNEDsuspend)

Description

This function retrieves various combinations of event flags from the specified event group. Ifthe group does not contain the necessary flags, suspension of the calling task is possible.

Functions Called

CSC_Place_On_List


TCC_Suspend_Task

[TCCT_Check_Stack]

TCCT_Current_Thread

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsEVC_Cleanup

December 15, 2006

EVC_CleanupUsage

VOID EVC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from an event group. It is notcalled unless a timeout or a task terminate is in progress. Note that protection (the same as atsuspension time) is already in effect.

Functions Called


Component DescriptionsEVCE_Create_Event_Group


EVCE_Create_Event_GroupUsage

STATUS EVCE_Create_Event_Group (NU_EVENT_GROUP *event_group_ptr, CHAR*name)

Description

This function performs error checking on the parameters supplied to the create event groupfunction.

Functions Called

EVC_Create_Event_Group


Component DescriptionsEVCE_Delete_Event_Group

December 15, 2006

EVCE_Delete_Event_GroupUsage

STATUS EVCE_Delete_Event_Group (NU_EVENT_GROUP *event_group_ptr)

Description

This function performs error checking on the parameters supplied to the delete event groupfunction.

Functions Called

EVC_Delete_Event_Group

Component DescriptionsEVCE_Set_Events


EVCE_Set_EventsUsage

STATUS EVCE_Set_Events (NU_EVENT_GROUP *event_group_ptr, UNSIGNED events,OPTION operation)

Description

This function performs error checking on the parameters supplied to the set events groupfunction.

Functions Called

EVC_Set_Events


Component DescriptionsEVCE_Retrieve_Events

December 15, 2006

EVCE_Retrieve_EventsUsage

STATUS EVCE_Retrieve_Events (NU_EVENT_GROUP *event_group_ptr, UNSIGNEDrequested_events, OPTION operation, UNSIGNED *retrieved_events, UNSIGNEDsuspend)

Description

This function performs error checking on the parameter supplied to the retrieve events function.

Functions Called

EVC_Retrieve_Events

TCCE_Suspend_Error

Component DescriptionsEVF_Established_Event_Groups


EVF_Established_Event_GroupsUsage

UNSIGNED EVF_Established_Event_Groups (VOID)

Description

This function returns the current number of established event groups. Event groups previouslydeleted are no longer considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsEVF_Event_Group_Pointers

December 15, 2006

EVF_Event_Group_PointersUsage

UNSIGNED EVF_Event_Group_Pointers (NU_EVENT_GROUP **pointer_list, UNSIGNEDmaximum_pointers)

Description

This function builds a list of event group pointers, starting at the specified location. The numberof event group pointers placed in the list is equivalent to the total number of event groups or themaximum number of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsEVF_Event_Group_Information


EVF_Event_Group_InformationUsage

STATUS EVF_Event_Group_Informa tion(NU_EVENT_GROUP event_group_ptr, CHAR*name, UNSIGNED *event_flags, UNSIGNED *tasks_waiting, NU_TASK **first_task)

Description

This function returns information about the specified event group. However, if the suppliedevent group pointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsPartition Memory Component (PM)

December 15, 2006

Partition Memory Component (PM)The partition memory component (PM) is responsible for processing all Nucleus PLUSpartition memory facilities. A Nucleus PLUS partition memory pool contains a specific numberof fixed-size memory partitions. Tasks may suspend while waiting for a memory partition froman empty pool. You can dynamically create and delete partition pools. See the Nucleus PLUSReference Manual for more detailed information about partition memory pools.

Partition Memory FilesThe Partition Memory Component (PM) consists of seven files. Each source file of thePartition Memory Component is defined in the following table.

Partition Memory Data Structures

Created Partition Memory ListNucleus PLUS partition pools may be created and deleted dynamically. The partition memorycontrol block (PCB) for each created partition memory pool is kept on a doubly linked, circularlist. Newly created partition memory pools are placed at the end of the list, while deletedpartition memory pools are completely removed from the list. The head pointer of this list isPMD_Created_Pools_List.

Table 4-43. Partition Memory File Names

File Description

pm_defs.h This file contains constants and data structure definitions specific tothe PM.

pm_extr.h All external interfaces to the PM are defined in this file.

pmd.c Global data structures for the PM are defined in this file.

pmf_established.c These files contain the information gathering functions for the PM.

pmf_info.c

pmf_pointers.c

pmc_common.c These files contain all of the core functions of the PM. Functions thathandle basic allocate-memory and deallocate-memory services aredefined in these files.pmc_deallocate.c

pmc_delete.c

pmce_common.c These files contain the error checking function interfaces for the corefunctions defined in pmc_ <function description>.c.

pmce_deallocate.c

pmce_delete.c



Figure 4-21. PMD Created Pools List

Created Partition Memory List ProtectionNucleus PLUS protects the integrity of the Created Partition Memory List from competing tasksand/or HISRs. This is done by using an internal protection structure called PMD_List_Protect.All partition memory creation and deletion is done under the protection of PMD_List_Protect.

Field Declarations


Field Summary

Total Partition PoolsThe total number of currently created Nucleus PLUS partition memory pools is contained in thevariable PMD_Total_Pools. The contents of this variable correspond to the number of PCBs onthe created list. Manipulation of this variable is also done under the protection of PMD_List_Protect.

Available Partitions ListThe Available Partitions List is a singly linked trailer terminated list, which contains theavailable partitions. The PCB contains pointers to the starting address of the list as well as thenext available partition in the list. Allocated partitions are removed from the front of the list, anddeallocated partitions are placed at the front of the list. Each partition has a header block thatlinks the partitions together.

Table 4-44.

Field Description

tc_tcb_ponter Identifies the thread that currently has the protection.




December 15, 2006

Figure 4-22. Available Partitions

Partition Pool Control BlockThe PCB PM_PCB contains the starting address of the current memory pool and other fieldsnecessary for processing partition pool requests.

Field Declarations

CS_NODE pm_createdUNSIGNED pm_idCHAR pm_name[NU_MAX_NAME]VOID *pm_start_addressUNSIGNED pm_pool_sizeUNSIGNED pm_partition_sizeUNSIGNED pm_availableUNSIGNED pm_allocatedstruct PM_HEADER_STRUCT *pm_available_listDATA_ELEMENT pm_fifo_suspendDATA_ELEMENT pm_padding[PAD_1]UNSIGNED pm_tasks_waitingstruct PM_SUSPEND_STRUCT *pm_suspension_list



Field Summary

Partition Memory Pool Header StructureThe partition header structure PM_HEADER is placed at the beginning of each availablepartition. Each header contains a pointer to the next available partition, except for the lastpartition, which points to a null terminator. Each partition header also contains a pointer to itsPCB.

Field Declarations

struct PM_HEADER_STRUCT *pm_next_availablePM_PCB *pm_partition_pool

Field Description

pm_created This is the link node structure for partition memory pools. It islinked into the created partition pools list, which is a doublylinked, circular list.

pm_id This holds the internal partition memory pool identification of0x50415254, which is equivalent to ASCII PART.

pm_name This is the user-specified, 8 character name for the partitionmemory pool.

*pm_start_address This is the starting address of the current partition memory pool.

pm_pool_size Holds the size of the partition memory pool.

pm_partition_size This is the size of the current memory pool partition.

pm_available This is the number of partitions available for use in the currentmemory pool.

pm_allocated Holds the number of allocated partitions.

*pm_available_list This is the list of available partitions of the current memory pool.

pm_fifo_suspend A flag that determines whether tasks suspend in FIFO or priorityorder.

pm_padding This is used to align the partition memory pool structure on aneven boundary. For most targets, this field is not used.

pm_tasks_waiting Indicates the number of tasks that are currently suspended on apartition memory pool.

*pm_suspension_list The head pointer of the partition memory pool suspension list. Ifno tasks are suspended, this pointer is NULL.



December 15, 2006

Field Summary

Partition Memory Pool Suspension StructureTasks can suspend on empty and full partition memory pool conditions. During the suspensionprocess a PM_SUSPEND structure is built. This structure contains information about the task andthe task’s partition pool request at the time of suspension. This suspension structure is linked tothe PCB in a doubly linked, circular list and is allocated from the suspending task’s stack.There is one suspension block for every task suspended on the partition memory pool.

The suspension block’s position on the suspend list is determined at partition pool creation. If aFIFO suspension was selected, the suspension block is added to the end of the list. Otherwise, ifpriority suspension was selected, the suspension block is placed after suspension blocks withtasks of equal or higher priority.

Figure 4-23. Partition Memory Pool Suspension Structure

Field Declarations

CS_NODE pm_suspend_linkPM_PCB *pm_partition_poolTC_TCB *pm_suspended_taskVOID *pm_return_status

Table 4-45.

Field Description

*pm_next_available A pointer to the next partition in the available list.

pm_partition_pool A pointer to this partition’s PCB.



Field Summary

Partition Memory FunctionsThe following sections provide a brief description of the functions in the PM. Review of theactual source code is recommended for further information.

Table 4-46.

Field Description

pm_suspend_link A link node structure for linking with other suspended blocks.It is used in a doubly linked, circular suspension list.

*pm_partition_pool A pointer to the partition memory pool structure.

*pm_suspended_task A pointer to the Task Control Block of the suspended task.

*pm_return_pointers The return memory address that has been requested.

pm_return_status The completion status of the task suspended on the partitionpool.


Component DescriptionsPMC_Create_Partition_Pool

December 15, 2006

PMC_Create_Partition_PoolUsage

STATUS PMC_Create_Partition_Pool (NU_PARTITION_POOL *pool_ptr, CHAR *name,VOID *start_address, UNSIGNED pool_size, UNSIGNED partition_size, OPTIONsuspend_type)

Description

This function creates a memory partition pool and then places it on the list of created partitionpools.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsPMC_Delete_Partition_Pool


PMC_Delete_Partition_PoolUsage

STATUS PMC_Delete_Partition_Pool (NU_PARTITION_POOL *pool_ptr)

Description

This function deletes a memory partition pool and removes it from the list of created partitionpools. All tasks suspended on the partition pool are resumed with the appropriate error status.Note that this function does not free any memory associated with either the pool area or the poolcontrol block. That is the responsibility of the application.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_Protect


TCCT_System_Protect


TCCT_Unprotect


Component DescriptionsPMC_Allocate_Partition

December 15, 2006

PMC_Allocate_PartitionUsage

STATUS PMC_Allocate_Partition (NU_PARTITION_POOL *pool_ptr, VOID*return_pointer, UNSIGNED suspend)

Description

This function allocates a memory partition from the specified memory partition pool. If amemory partition is currently available, this function is completed immediately. Otherwise, ifthere is no partition currently available, suspension is possible.

Functions Called

CSC_Place_On_List



TCC_Suspend_Task

TCC_Task_Priority

[TCCT_Check_Stack]

TCCT_Current_Thread

TCCT_System_Protect

TCCT_Unprotect

Component DescriptionsPMC_Deallocate_Partition


PMC_Deallocate_PartitionUsage

STATUS PMC_Deallocate_Partition (VOID *partition)

Description

This function deallocates a previously allocated partition. If there is a task waiting for apartition, the partition is simply given to the waiting task, and the waiting task is resumed.Otherwise, the partition is returned to the partition pool.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsPMC_Cleanup

December 15, 2006

PMC_CleanupUsage

VOID PMC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from a partition pool. It is notcalled unless a timeout or a task terminate is in progress. Note that protection (the same as atsuspension time) is already in effect.

Functions Called


Component DescriptionsPMCE_Create_Partition_Pool


PMCE_Create_Partition_PoolUsage

STATUS PMCE_Create_Partition_Pool (NU_PARTITION_POOL *pool_ptr, CHAR *name,VOID *start_address, UNSIGNED pool_size, UNSIGNED partition_size, OPTIONsuspend_type)

Description

This function performs error checking on the parameters supplied to the create partition poolfunction.

Functions Called

PMC_Create_Partition_Pool


Component DescriptionsPMCE_Delete_Partition_Pool

December 15, 2006

PMCE_Delete_Partition_PoolUsage

STATUS PMCE_Delete_Partition_Pool (NU_PARTITION_POOL *pool_ptr)

Description

This function performs error checking on the parameters supplied to the delete partition poolfunction.

Functions Called

PMC_Delete_Partition_Pool

Component DescriptionsPMCE_Allocate_Partition


PMCE_Allocate_PartitionUsage

STATUS PMCE_Allocate_Partition (NU_PARTITION_POOL *pool_ptr, VOID**return_pointer, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the allocate partitionfunction.

Functions Called

PMC_Allocate_Partition

TCCE_Suspend_Error


Component DescriptionsPMCE_Deallocate_Partition

December 15, 2006

PMCE_Deallocate_PartitionUsage

STATUS PMCE_Deallocate_Partition (VOID *partition)

Description

This function performs error checking on the parameters supplied to the deallocate partitionfunction.

Functions Called

PMC_Deallocate_Partition

Component DescriptionsPMF_Established_Partition_Pools


PMF_Established_Partition_PoolsUsage

UNSIGNED PMF_Established_Partition_Pools (VOID)

Description

This function returns the current number of established partition pools. Pools previouslydeleted are no longer considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsPMF_Partition_Pool_Pointers

December 15, 2006

PMF_Partition_Pool_PointersUsage

UNSIGNED PMF_Partition_Pool_Pointers (NU_PARTITION_POOL *pointer_list,UNSIGNED maximum_pointers)

Description

This function builds a list of pool pointers, starting at the specified location. The number of poolpointers placed in the list is equivalent to the total number of pools or the maximum number ofpointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsPMF_Partition_Pool_Information


PMF_Partition_Pool_InformationUsage

STATUS PMF_Partition_Pool_Information (NU_PARTITION_POOL *pool_ptr, CHAR*name, VOID **start_address, UNSIGNED *pool_size, UNSIGNED *partition_size,UNSIGNED *available, UNSIGNED *allocated, OPTION *suspend_type, UNSIGNED*tasks_waiting, NU_TASK **first_task)

Description

This function returns information about the specified partition pool. However, if the suppliedpartition pool pointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsDynamic Memory Component (DM)

December 15, 2006

Dynamic Memory Component (DM)The dynamic memory component (DM) is responsible for processing all Nucleus PLUSdynamic memory facilities. A Nucleus PLUS dynamic memory pool contains a user-specifiednumber of bytes. The memory location of the pool is determined by the application. Tasks maysuspend while waiting for enough dynamic memory to become available. You can dynamicallycreate and delete dynamic pools. See the Nucleus PLUS Reference Manual for more detailedinformation about dynamic memory pools.

Dynamic Memory FilesThe DM consists of seven files. Each source file of the Dynamic Memory Component isdefined in the following table.

Table 4-47.

Field Description

dm_defs.h This file contains constants and data structure definitions specific to theDM.

dm_extr.h All external interfaces to the DM are defined in this file.

dmd.c Global data structures for the DM are defined in this file.

dmf_established.c These files contain the information gathering functions for the DM.

dmf_info.c

dmf_pointers.c

dms_aligned.c These files contain the supplemental functions for the DM.

dmc_common.c These files contain all of the core functions of the DM. Functions thathandle basic allocate-memory and deallocate memory services aredefined in these files.dmc_deallocate.c

dmc_delete.c

dmce_common.c These files contain the error checking function interfaces for the corefunctions defined in dmc_<function description>.c.

dmce_deallocate.c

dmce_delete.c



Figure 4-24. DMD Created Pools List

Dynamic Memory Data Structures

Created Dynamic Memory ListNucleus PLUS dynamic memory pools may be created and deleted dynamically. The dynamicmemory pool control block (PCB) for each created dynamic memory pool is kept on a doublylinked, circular list. Newly created dynamic memory pools are placed at the end of the list,while deleted dynamic memory pools are completely removed from the list. The head pointerof this list is DMD_Created_Pools_List.

Created Dynamic Memory List ProtectionNucleus PLUS protects the integrity of the Created Dynamic Memory List from competingtasks and/or HISRs. This is done by using an internal protection structure called DMD_List_Protect. All dynamic memory creation and deletion is done under the protection of DMD_List_Protect.

Field Declarations




December 15, 2006

Field Summary

Figure 4-25. Available Memory List

Total Dynamic PoolsThe total number of currently created Nucleus PLUS dynamic memory pools is contained in thevariable DMD_Total_Pools. The content of this variable corresponds to the number of PCBs onthe created list. Manipulation of this variable is also done under the protection of DMD_List_Protect.

Available Memory ListThe Available Memory List is a doubly linked, NULL terminated, circular list, which containsthe available dynamic memory blocks. The PCB contains pointers to the starting address of thelist as well as the next available block in the list. A search pointer is also contained in the PCB.It linearly searches for and accumulates available memory blocks in order to fill memoryrequests. Allocated blocks are removed from the front of the list and deallocated blocks areplaced back in the list at the point where they came from. Each block includes a header thatlinks the various blocks together.

Table 4-48.

Field Description





Dynamic Pool Control BlockThe dynamic memory pool control block DM_PCB contains the starting address of the currentmemory pool and other fields necessary for processing dynamic memory pool requests.

Field Declarations

CS_NODE dm_createdTC_PROTECT dm_protectUNSIGNED dm_idCHAR dm_name[NU_MAX_NAME]VOID *dm_start_addressUNSIGNED dm_pool_sizeUNSIGNED dm_min_allocationUNSIGNED dm_availablestruct DM_HEADER_STRUCT *dm_memory_list structDM_HEADER_STRUCT *dm_search_ptrDATA_ELEMENT dm_fifo_suspendDATA_ELEMENT dm_padding[PAD_1]UNSIGNED dm_tasks_waitingstruct DM_SUSPEND_STRUCT *dm_suspension_list



December 15, 2006

Field Summary

Dynamic Memory Pool Header StructureThe dynamic header structure DM_Header is placed at the beginning of each available memoryblock. Each header contains pointers to both the next available memory block and the previousavailable memory block. The last block’s next pointer points to a null terminator. Eachdynamic memory header also contains a pointer to its PCB.

Field Declarations

struct DM_HEADER_STRUCT *dm_next_memorystruct DM_HEADER_STRUCT *dm_previous_memoryDATA_ELEMENT dm_memory_freeDM_PCB *dm_memory_pool

Table 4-49.

Field Description

dm_created This is the link node structure for dynamic memory pools. It is linkedinto the created dynamic pools list, which is a doubly linked, circularlist.

dm_protect A pointer to the protection structure for the dynamic memory pool.

dm_id This holds the internal dynamic memory pool identification of0x44594E41, which is equivalent to ASCII DYNA.

dm_name This is the user-specified, 8 character name for the dynamic memorypool.

*dm_start_address This is the starting address of the current dynamic memory pool.

dm_pool_size Holds the size of the dynamic memory pool.

dm_min_allocation The minimum number of bytes to be allocated in a block.

dm_available This is the total number of bytes available for use in the currentmemory pool.

*dm_memory_list A list of the memory blocks in the current memory pool.

*dm_search_ptr The search pointer used for locating a dynamic memory pool header.

dm_fifo_suspend A flag that determines whether tasks suspend in FIFO or priorityorder.

dm_padding This is used to align the dynamic memory pool structure on an evenboundary. For most targets, this field is not used.

dm_tasks_waiting Indicates the number of tasks that are currently suspended on adynamic memory pool.

*dm_suspension_list The head pointer of the dynamic memory pool suspension list. If notasks are suspended, this pointer is NULLE.



Field Summary

Dynamic Memory Pool Suspension StructureTasks can suspend on empty and full dynamic memory pool conditions. During the suspensionprocess a DM_SUSPEND_STRUCT structure is built. This structure contains informationabout the task and the task’s dynamic pool request at the time of suspension. This suspensionstructure is linked onto the PCB in a doubly linked, circular list and is allocated off of thesuspending task’s stack. There is one suspension block for every task suspended on thedynamic memory pool.

The order of the suspension block placement on the suspend list is determined at dynamic poolcreation. If a FIFO suspension was selected, the suspension block is added to the end of the list.Otherwise, if priority suspension was selected, the suspension block is placed after suspensionblocks for tasks of equal or higher priority.

Figure 4-26. Dynamic Memory Pool Suspension Structure

Field Declarations

CS_NODE dm_suspend_linkDM_PCB *dm_memory_poolUNSIGNED dm_request_sizeTC_TCB *dm_suspended_taskVOID *dm_return_pointerSTATUS dm_return_status

Table 4-50.

Field Description

*dm_next_memory A pointer to the next memory block in the available list.

*dm_previous_memory A pointer to the previous memory block in the available list.

dm_memory_free A flag that indicates if the current memory block is free.

dm_memory_pool A pointer to the PCB, which this memory block belongs to.



December 15, 2006

Field Summary

Dynamic Memory FunctionsThe following sections provide a brief description of the functions in the DM. Review of theactual source code is recommended for further information.

Table 4-51.

Field Description

dm_suspend_link A link node structure for linking with other suspendedblocks. It is used in a doubly linked, circularsuspension list.

*dm_memory_pool A pointer to the dynamic memory pool structure.

dm_request_size Contains the size of the requested memory block.

*dm_suspended_task A pointer to the Task Control Block of the suspendedtask.

*dm_return_pointer The return memory address that has been requested.

dm_return_status The completion status of the task suspended on thedynamic pool.

Component DescriptionsDMC_Create_Memory_Pool


DMC_Create_Memory_PoolUsage

STATUS DMC_Create_Memory_Pool (NU_MEMORY_POOL *pool_ptr, CHAR *name,VOID *start_address, UNSIGNED pool_size, UNSIGNED min_allocation, OPTIONsuspend_type)

Description

This function creates a dynamic memory pool and then places it on the list of created dynamicmemory pools. If the list does not exist, then this pool becomes the first item in the dynamicmemory pools list.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsDMC_Delete_Memory_Pool

December 15, 2006

DMC_Delete_Memory_PoolUsage

STATUS DMC_Delete_Memory_Pool (NU_MEMORY_POOL *pool_ptr)

Description

This function deletes a dynamic memory pool and removes it from the list of created memorypools. All tasks suspended on the memory pool are resumed with the appropriate error status.Note that this function does not free any memory associated with either the pool area or the poolcontrol block. That is the responsibility of the application.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]


TCCT_Protect


TCCT_System_Protect


TCCT_Unprotect

Component DescriptionsDMC_Allocate_Memory


DMC_Allocate_MemoryUsage

STATUS DMC_Allocate_Memory (NU_MEMORY_POOL *pool_ptr, VOID**return_pointer, UNSIGNED size, UNSIGNED suspend)

Description

This function allocates memory from the specified dynamic memory pool. If enough dynamicmemory is currently available, this function is completed immediately. Otherwise, tasksuspension is possible.

Functions Called

CSC_Place_On_List


TCC_Suspend_Task

TCC_Task_Priority

[TCCT_Check_Stack]

TCCT_Current_Thread

TCCT_Protect

TCCT_Set_Suspend_Protect

TCCT_System_Protect

TCCT_Unprotect



Component DescriptionsDMC_Deallocate_Memory

December 15, 2006

DMC_Deallocate_MemoryUsage

STATUS DMC_Deallocate_Memory (VOID *memory)

Description

This function deallocates a previously allocated dynamic memory block. The deallocateddynamic memory block is merged with any adjacent neighbors. This insures that there are noconsecutive blocks of free memory in the pool, which makes the search easier. If there is a taskwaiting for dynamic memory, a determination of whether or not the request can now be satisfiedis made after the deallocation is complete.

Functions Called



TCC_Resume_Task

[TCCT_Check_Stack]



TCCT_System_Protect


TCCT_Protect

TCCT_Unprotect

Component DescriptionsDMC_Cleanup


DMC_CleanupUsage

VOID DMC_Cleanup (VOID *information)

Description

This function is responsible for removing a suspension block from a memory pool. It is notcalled unless a timeout or a task terminate is in progress. Note that protection (the same as atsuspension time) is already in effect.

Functions Called



Component DescriptionsDMCE_Create_Memory_Pool

December 15, 2006

DMCE_Create_Memory_PoolUsage

STATUS DMCE_Create_Memory_Pool (NU_MEMORY_POOL *pool_ptr, CHAR *name,VOID *start_address, UNSIGNED pool_size, UNSIGNED min_allocation, OPTIONsuspend_type)

Description

This function performs error checking on the parameters supplied to create the dynamicmemory pool function.

Functions Called

DMC_Create_Memory_Pool

Component DescriptionsDMCE_Delete_Memory_Pool


DMCE_Delete_Memory_PoolUsage

STATUS DMCE_Delete_Memory_Pool (NU_MEMORY_POOL *pool_ptr)

Description

This function performs error checking on the parameters supplied to the delete dynamicmemory pool function.

Functions Called

DMC_Delete_Memory_Pool


Component DescriptionsDMS_Allocate_Aligned_Memory

December 15, 2006

DMS_Allocate_Aligned_MemoryUsage

STATUS DMS_Allocate_Aligned_Memory (NU_MEMORY_POOL *pool_ptr, VOID**return_pointer, UNSIGNED size, UNSIGNED alignment, UNSIGNED suspend)

Description

This function allocates memory on a specified alignment from the specified dynamic memorypool. If dynamic memory is currently available on the proper alignment, this function iscompleted immediately. Otherwise, if there is not enough memory currently available or theproper alignment, task suspension is possible.

Functions Called

CSC_Place_on_list


TCC_Suspend_Task

TCC_Task_Priority

[TCCT_Check_Stack]

TCCT_Current_Thread

TCCT_Protect


TCCT_System_Protect

TCCT_Unprotect


Component DescriptionsDMCE_Allocate_Memory


DMCE_Allocate_MemoryUsage

STATUS DMCE_Allocate_Memory (NU_MEMORY_POOL *pool_ptr, VOID**return_pointer, UNSIGNED size, UNSIGNED suspend)

Description

This function performs error checking on the parameters supplied to the allocate memoryfunction.

Functions Called

DMC_Allocate_Memory

TCCE_Suspend_Error


Component DescriptionsDMCE_Deallocate_Memory

December 15, 2006

DMCE_Deallocate_MemoryUsage

STATUS DMCE_Deallocate_Memory (VOID *memory)

Description

This function performs error checking on the parameters supplied to the deallocate memoryfunction.

Functions Called

DMC_Deallocate_Memory

Component DescriptionsDMF_Established_Memory_Pools


DMF_Established_Memory_PoolsUsage

UNSIGNED DMF_Established_Memory_Pools (VOID)

Description

This function returns the current number of established memory pools. Pools previouslydeleted are no longer considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsDMF_Memory_Pool_Pointers

December 15, 2006

DMF_Memory_Pool_PointersUsage

UNSIGNED DMF_Memory_Pool_Pointers (NU_MEMORY_POOL **pointer_list,UNSIGNED maximum_pointers)

Description

This function builds a list of pool pointers, starting at the specified location. The number ofpool pointers placed in the list is equivalent to the total number of pools or the maximumnumber of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsDMF_Memory_Pool_Information


DMF_Memory_Pool_InformationUsage

STATUS DMF_Memory_Pool_Information (NU_MEMORY_POOL *pool_ptr, CHAR*name, VOID **start_address, UNSIGNED *pool_size, UNSIGNED*min_allocation,UNSIGNED *available, OPTION *suspend_type, UNSIGNED *tasks_waiting, NU_TASK**first_task)

Description

This function returns information about the specified memory pool. However, if the suppliedmemory pool pointer is invalid, the function simply returns an error status.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsZero Copy Component (ZC)

December 15, 2006

Zero Copy Component (ZC)The zero copy component (ZC) is a method of data abstraction designed to allow multipleprogram modules to share data without repeatedly copying data from place to place. The ZCfunctions improve performance by eliminating the need for repeated copying of memory.Multiple application modules may directly share data stored in a ZC data buffer by simplypassing the ZC buffer identifier (ZC_BUF_ID) to all modules requiring access to the data.

Utilizing the ZC component for any applications or middleware requiring data regions to beshared by many tasks greatly improves the performance of these operations (versus makingseparate copies of the data).

Providing this component supplies all Nucleus Middleware and application writers an API thatcan be used to perform this functionality without implementing a separate version for eachapplication. The main benefits of ZC are code reuse and the resultant single point ofoptimization for data sharing operations.

Zero Copy FilesThe files that comprise the ZC component as listed in the following table.

Table 4-52. Zero Copy Component Files

File Purpose

zc_extr.h This file is provides the user with the ZC API definitions and functionprototypes

zc_defs.h This file contains ZC structure definitions, macros, and data typesthat are internally utilized

zcd.c This file holds all global data utilized by the ZC software

zc_active.c The functions contained in this file are active in nature. Thesefunctions cause the internal data elements within the ZC software tobe modified and cause ZC data objects to be created, deleted, ormodified.

zc_passive.c This file contains functions that are passive in nature. Thesefunctions do not cause data within the ZC software to be modified.These functions are simply used to obtain data from the ZC objects orinformation about the ZC objects.

zce_active.c The functions in this file are the error handling shells for the activefunctions within the ZC software

zce_passive.c The functions in this file are the error handling shells for the passivefunctions within the ZC software



Zero Copy Data StructuresThe following are the object types utilized within the ZC software:

GLOBAL DATA

AVAILABLE

BUFFER

SEGMENT

DATA

Each object is a fixed sized array and all objects utilize the same size array. The differencebetween the various object types is the use of the space within the object. The number ofelements and purpose of each element varies between each type of object. The followingdiagram depicts the different object types and their corresponding usage of the object dataspace. A full description of each object type follows the diagram.

Figure 4-27. Object Types and Usages

These objects are created and initialized through a combination of compile time configurationsettings and dynamically during the initialization of the ZC software.

All the ZC data objects are allocated in one contiguous memory space and each object isformatted identically during the ZC software initialization sequence. The purpose and use ofeach object is described in the following paragraphs. Additionally, the methods used to identifyand address a ZC object are outlined below.



December 15, 2006

Object IdentificationEach object is identified / addressed utilizing the OBJECT IDENTIFIER (ID). The OBJECTID is simply the object's relative offset from the start of the contiguous block of objectsallocated in the ZC software. For instance, the first object within this contiguous memory hasan OBJECT ID of 0 - this object's relative offset to the beginning of the memory is 0. Theobject immediately following this first object has an OBJECT ID of 1; the next object has an IDof 2, and so on. Therefore, object IDs will be a value from 0 to N (where N is the total numberof objects minus one since the object IDs start at 0).

For more information and description on the object initialization, refer to the NU_ZC_Initializefunction in the zc_active.c file.

ZC_GLOBAL_DATA OBJECT TYPEThe GLOBAL DATA object type is used by a single object (OBJECT ID 0). This object is notavailable for allocation or use as any other object type. The purpose of the GLOBAL DATAobject is to hold all critical global data associated with the ZC software. The data containedwithin this object is accessed and manipulated through the various ZC APIs. The Global DataObject is described by the ZC_GLOBAL_DATA array described below.

Field Declarations

UINT32 avail_head_id;UINT32 avail_tail_id;UINT32 count_bits;UINT32 count_bit_mask;UINT32 total_objects;

Field Summary

Table 4-53.

Field Description

avail_head_id Object ID of first available object.

avail_tail_id Object ID of last available object.

count_bits Number of bits used as count bits for the unique 32-bit ID for buffers.

count_bit_mask Value used to mask out all but count bits within a 32-bit ID for abuffer.

total_objects Total number of objects in the system.



ZC_AVAILABLE OBJECT TYPEThe AVAILABLE object type is used when an object is available for allocation (i.e. it is not aBUFFER, SEGMENT, or DATA object type). In essence, a pool of data objects will beavailable when initialization is completed and each object can be allocated for use as any of thethree in-use object types (BUFFER, SEGMENT, and DATA). After being allocated, the objecttype (refer to the previous ZC Object illustration) is modified to reflect its corresponding usage.The object may also be de-allocated and returned to the available pool through use of thevarious ZC APIs; this causes the object type to return to AVAILABLE. The Available object isdescribed by the ZC_AVAILABLE array described below.

Field Declarations

UINT32 type;UINT32 unused;UINT32 next_obj_id;

Field Summary

ZC_BUFFER OBJECT TYPEThe BUFFER object type is used to maintain information about the head and tail SEGMENTobjects that constitute a ZC buffer. This object also contains the total size of all data referencedby the ZC buffer. The Buffer Object is described by the ZC_BUFFER array described below.

Field Declarations

UINT32 type;UINT32 id;UINT32 head_seg_id;UINT32 tail_seg_id;UINT32 length;

Table 4-54.

Field Description

type Set to ZC_AVAILABLE_TYPE

unused Not used for ZC_AVAILABLE object

next_obj_id ID of next available object



December 15, 2006

Field Summary

ZC_SEGMENT OBJECT TYPEThe SEGMENT object type maintains the segment IDs of any adjacent ZC segments. Zero,one, or many ZC segments constitute a given ZC buffer. Additionally, each SEGMENT objecttype references a single DATA object (see DATA definition below). To allow a ZC segment toreference any portion of the data defined by the DATA object, the SEGMENT object maintains“an offset to” and “a length of” the data referenced. The Segment Object is described by theZC_SEGMENT array described in the following section.

Field Declarations

UINT32 type;UINT32 unused;UINT32 parent_id;UINT32 next_seg_id;UINT32 prev_seg_id;UINT32 data_obj_id;UINT32 mem_offset;UINT32 length;

Field Summary

Table 4-55.

Field Description

type Set to ZC_BUFFER_TYPE

id Holds ZC_Object_Id and ZC_Object_Count_Bits

head_seg_id ID of First Segment in the ZC Buffer (may be NULL)

tail_seg_id ID of Last Segment in the ZC Buffer (may be NULL)

length Total number of data bytes contained in the ZC Buffer

Table 4-56.

Field Description

type Set to ZC_SEGMENT_TYPE.

unused Not used for ZC_SEGMENT object.

parent_id ID of the ZC_BUFFER that the Segment is part of.

next_seg_id ID of Next Segment in the ZC Buffer (may be NULL).

prev_seg_id ID of Previous Segment in the ZC Buffer (may be NULL).

data_obj_id ID to the ONE ZC_DATA object referenced by this Segment.



ZC_DATA OBJECT TYPEThe DATA object type contains information specific to a given memory region. A memoryregion may be managed / owned by the application or by the ZC software. The DATA objectmaintains the following information for the memory region it references: the number of ZCsegments that reference the memory, the start address of the memory, the size of the memoryregion, an application call-back function pointer associated with the memory, and a call-backfunction parameter. When the number of ZC segments referencing an application's memoryregion reaches zero (as a result of ZC API calls), the call-back function associated with thememory is invoked. This allows the memory region to be handled, as required, by theapplication (de-allocate, reuse, and so on.). The Data Object is described by the ZC_DATAarray described in the following section.

Field Declarations

UINT32 type;UINT32 unused;UINT32 data_refs;UINT32 mem_ptr;UINT32 length;UINT32 cb_func_ptr;UINT32 cb_param;

Field Summary

mem_offset Positive offset, from the start of the memory buffer pointed to by thissegment, to the memory referenced.

length Length of the memory (from the mem_offset) referenced by thisSegment.

Table 4-57.

Field Description

type Set to ZC_DATA_TYPE.

unused Not used for ZC_DATA object.

data_refs Number of ZC Segments that reference this data.

mem_ptr Pointer to the memory region that this object references.

length Length of the memory region referenced by this object.

cb_func_ptr Pointer to the application supplied call-back function.

cb_param Application supplied parameter for the call-back function.

Table 4-56. (cont.)

Field Description



December 15, 2006

Data Access within the ZC BufferThe data contained within a specific ZC buffer is accessed using a ZC segment identifier and abyte offset. The byte offset may be a positive or negative value. The byte offset simplyrepresents the number of bytes from the beginning of the specified ZC segment to the start ofthe data being addressed. The byte offset may be larger than the number of bytes referenced bythe specified ZC segment, but it cannot reference data that is outside of the ZC buffer.

The following figure illustrates how the ZC objects relate to each other.

Figure 4-28. ZC Object Relationships



ZC FunctionsThe following table lists the ZC functions that constitute the internal API available to ZCfunctions. Each of these internal APIs is described in this section of the manual.

NoteIn the following discussion under the “Function/Macros Called” section, functions arerepresented by mixed case words (Ex; ZC_Object_Allocate) whereas macros arerepresented by uppercase words (Ex; ZC_DATA_REF_ADD).

Table 4-58.

Function Name Function Purpose

ZC_Seg_Create Creates a ZC segment

ZC_Seg_Chain_Insert Inserts a ZC segment chain (one or more segments) into a zerocopy buffer starting at the specified segment and offset

ZC_Seg_Split Splits a ZC segment into two segments

ZC_Seg_Data_Remove Removes data from a segment

ZC_Seg_Delete Deletes a ZC segment.

ZC_Data_Create Creates a ZC data object

ZC_Data_Ref_Remove Removes a ZC data reference (decrements Number of DataReferences by one). This function may invoke the Data Callbackfunction

ZC_Obj_Allocate Allocates a ZC object for use from the Available Objects pool

ZC_Obj_Deallocate Deallocates a ZC object by returning it to the Available Objectspool

ZC_Mem_Allocate Allocates specified amount of memory (uses NU_Allocate_Memory)

ZC_Mem_Free Free specified memory (uses NU_Deallocate_Memory)

ZCE_Buf_Seg_Error_Check

Checks for an error in buffer IDs and segment IDs that arecontained within the specified buffer.


Component DescriptionsZC_Seg_Create

December 15, 2006

ZC_Seg_CreateUsage

STATIC ZC_OBJ_ID ZC_Seg_Create(ZC_BUF_ID parent_id, ZC_SEG_ID prev_seg,ZC_SEG_ID next_seg, ZC_OBJ_ID data_obj_id, INT offset, INT length)

Description

This function creates a ZC segment object and populates the object with the passed parameters.If the object is created successfully the ZC_OBJ_ID of the created ZC segment is returned. AnNU_NULL is returned if an error occurs. This function performs the following actions:

Calls ZC_Obj_Allocate (ZC_SEGMENT_TYPE) to obtain a new ZC_SEGMENT object.

Writes the passed segment parameters into the new ZC segment’s fields.

Increments the data_refs element within the ZC data object that the new ZC segment refers

Functions / Macros Called

ZC_Object_Allocate

ZC_DATA_REF_ADD

Component DescriptionsZC_Seg_Chain_Insert


ZC_Seg_Chain_InsertUsage

STATIC ZC_SEG_ID ZC_Seg_Chain_Insert (ZC_BUF_ID dst_buf_id, ZC_OBJ_IDdst_seg_id, INT dst_offset, ZC_OBJ_ID src_head_seg_id, ZC_OBJ_ID src_tail_seg_id,INT src_length)

Description

This function inserts a ZC segment chain (one or more segments) into a ZC buffer starting at thespecified segment / offset. If the operation is completed successfully, the ZC_SEG_ID of thefirst inserted ZC segment is returned. An NU_NULL is returned if an error occurs. Thisfunction performs the following actions:

Tests to determine if the specified insertion point (segment / offset) is at the beginning, end, orsomewhere within the specified destination ZC buffer. For and insertion at the beginning or endof the specified destination ZC buffer the appropriate next_seg_id and prev_seg_id elements ofthe existing ZC buffers head or tail segments are adjusted to link them to the ZC segment chainbeing inserted. Also the ZC buffer’s head_seg_id or tail_seg_id is adjusted to point to the startof the first segment of the inserted chain.

When the insertion point is within the destination ZC buffer the dst_offset is tested to determineif a segment must be split or if the ZC segment chain is to be inserted between existingsegments. For an insertion between existing segments the appropriate next_seg_id and prev_seg_id elements of the existing segments are adjusted to link them to the ZC segment chainbeing inserted.

When an existing segment must be split to insert the segment chain the ZC_Seg_Split functionis called and the segment chain is then inserted between the two segments that acre created as aresult of the split.

The ZC buffer’s length element is adjusted to add the length of the inserted segment chain.


ZC_OBJ_PTR_FROM_BUF_ID_GET

ZC_BUF_BEGIN_CHECK

ZC_BUF_END_CHECK

ZC_OBJ_PTR_GET

ZC_Seg_Split


Component DescriptionsZC_Seg_Split

December 15, 2006

ZC_Seg_SplitUsage

STATIC ZC_SEG_ID ZC_Seg_Split(ZC_BUF_ID buf_obj_id, ZC_OBJ_ID seg_obj_id, INToffset)

Description

This function splits a zero copy segment into two segments. This requires creating a newsegment that references the same data object as the segment being split. If the operation iscompleted successfully, the ZC_SEG_ID of the ZC segment created that starts at the specifiedsplit offset is returned. An NU_NULL is returned if an error occurs. This function performsthe following actions:

Calls ZC_Seg_Create using the passed parameters to obtain a new ZC_Segment object.

Adjusts the appropriate next_seg_id and prev_seg_id elements of the ZC segment being splitand the new ZC segment to link them together. Also if the segment being split is the ZCbuffer’s head_seg_id or tail_seg_id, those elements are adjusted to correctly link to the splitsegments.

When the insertion point is within the destination ZC buffer the dst_offset is tested to determineif a segment must be split or if the ZC segment chain is to be inserted between existingsegments. For an insertion between existing segments the appropriate next_seg_id and prev_seg_id elements of the existing segments are adjusted to link them to the ZC segment chainbeing inserted.

When an existing segment must be split to insert the segment chain the ZC_Seg_Split functionis called and the segment chain is then inserted between the two segments that are created as aresult of the split.

Functions/Macros Called

ZC_OBJ_PTR_GET

ZC_Seg_Create


Component DescriptionsZC_Seg_Data_Remove


ZC_Seg_Data_RemoveUsage

STATIC INT ZC_Seg_Data_Remove (ZC_BUF_ID buf_id, ZC_SEG_ID * seg_id, INToffset, INT length)

Description

This function removes data from a segment. This may result in the removal of a ZC data objectif an entire segment’s data is removed and that segment was the only segment referencing theZC data object. If the operation is completed successfully, the number of data bytes removed isreturned. A zero is returned if an error occurs. The location pointed at by the passed seg_idpointer is updated with the ZC_SEG_ID of the segment that follows the data removed. If thereis no data following the removed data the location pointed at by the passed seg_id pointer is setto ZC_SEG_NONE. The length of the ZC buffer is reduced by the number of bytes removed.This function performs the following actions:

Removes from the specified ZC buffer the number of data bytes specified by the lengthparameter, starting at the specified segment / offset location.

When the data being removed is at the start or end of a segment the segment’s offset or length isadjusted to remove the specified data.

If the removed data is all data referenced by the specified segment, the segment is removedfrom the ZC buffer by calling ZC_Seg_Delete.

When the data to be removed is within an existing segment the segment must be split into twosegments. The ZC_Seg_Split function is called and the new segment created is then insertedafter the segment that was split.



ZC_OBJ_PTR_GET

ZC_Seg_Split

ZC_Seg_Delete


Component DescriptionsZC_Seg_Delete

December 15, 2006

ZC_Seg_DeleteUsage

STATIC VOID ZC_Seg_Delete (ZC_BUF_ID buf_id, ZC_SEG_ID * seg_id)

Description

This function removes data a ZC segment from the specified ZC buffer. This may result in theremoval of a ZC data object if the segment removed was the only segment referencing the ZCdata object. This function performs the following actions:

Removes from the specified ZC buffer the specified segment.

If the segment removed was the only segment referencing the segment’s ZC data object, thenthe ZC data object is also removed (from within the ZC_Data_Ref_Remove function).

Adjusts the appropriate next_seg_id and prev_seg_id elements of the ZC segments that werelinked to the segment removed. Also if the segment removed was the ZC buffer’s head_seg_idor tail_seg_id, those elements are adjusted to correctly link to the remaining segments.



ZC_OBJ_PTR_GET

ZC_ONE_SEG_CHECK

ZC_Obj_Deallocate

ZC_Data_Ref_Remove

Component DescriptionsZC_Data_Create


ZC_Data_CreateUsage

STATIC ZC_OBJ_ID ZC_Data_Create (CHAR * mem_ptr, INT length, VOID (*cb_func)(CHAR *, INT), INT cb_param)

Description

This function creates a zero copy data object and populates it with the passed parameters. If thedata object is created successfully the ZC_OBJ_ID of the created ZC data object is returned.An NU_NULL is returned if an error occurs. This function performs the following actions:

Calls ZC_Obj_Allocate (ZC_DATA_TYPE) to obtain a new ZC_DATA object.

Writes the passed data object parameters into the new ZC data object’s fields.


ZC_Obj_Allocate

ZC_OBJ_PTR_GET


Component DescriptionsZC_Data_Ref_Remove

December 15, 2006

ZC_Data_Ref_RemoveUsage

STATIC VOID ZC_Data_Ref_Remove (ZC_OBJ_ID data_obj_id)

Description

This function removes (decrements by one) a ZC data object’s data_refs element. Whenever aZC segment is deleted, it must de-reference its data. If the data is no longer referenced after thisde-referencing, a call-back function associated with the ZC data object is invoked. Thisfunction performs the following actions:

Decrements the ZC data object’s data_refs element by one.

Tests if the ZC data object’s data_refs element is zero and if so calls the associated callbackfunction to allow the owner of the data region to handle any actions required.

When the callback function returns (or if there is no callback function pointer) the ZC_Obj_Deallocate function is called to return the ZC data object to the AVAILABLE object pool.


ZC_OBJ_PTR_GET

ZC_Obj_Deallocate

Component DescriptionsZC_Obj_Allocate


ZC_Obj_AllocateUsage

STATIC ZC_OBJ_ID ZC_Object_Allocate (ZC_OBJ_TYPE obj_type)

Description

This function allocates a ZC object from the Available object pool and sets the object’s type tothe passed in object type. If the object is allocated successfully the ZC_OBJ_ID of the createdobject is returned. An NU_NULL is returned if an error occurs. This function performs thefollowing actions:

Gets the avail_head_id of the next available ZC object from the ZC_GLOBAL_DATA arrayand removes that object from the list of Available objects.

Writes the passed object type into the allocated object’s type field.


ZC_GLOBAL_DATA_GET


Component DescriptionsZC_Obj_Deallocate

December 15, 2006

ZC_Obj_DeallocateUsage

STATIC VOID ZC_Object_Deallocate (ZC_OBJ_ID obj_id)

Description

This function deallocates a ZC object and returns it to the Available object pool. This functionperforms the following actions:

Gets the ZC_OBJ_ID of the last available ZC object (avail_tail_id) from the ZC_GLOBAL_DATA array and links the object being returned into the list as the new avail_tail_id.


ZC_OBJ_PTR_GET

ZC_GLOBAL_DATA_GET

Component DescriptionsZC_Mem_Free


ZC_Mem_FreeUsage

STATIC VOID * ZC_Mem_Allocate (INT size)

Description

This function deallocates a specified amount of memory that the ZC code no longer needs. Thisfunction performs the following actions:

Calls NU_Deallocate_Memory to release the specified amount of memory that had been usedby the ZC code.


NU_Deallocate_Memory


Component DescriptionsZC_Buf_Seg_Error_Check

December 15, 2006

ZC_Buf_Seg_Error_CheckUsage

INT ZC_Seg_Delete (ZC_BUF_ID buf_id, ZC_SEG_ID seg_id)

Description

This function checks for possible errors in buffer IDs and segment IDs that are contained withinthe specified buffer. This function performs the following actions:

Verifies that the passed ZC buffer ID is valid (non-null) and points to a ZC_BUFFER object.

When the passed segment ID is not zero additional checks are made to ensure that the segmentis part of (owned by) the specified ZC_BUFFER object, and that the segment is not empty.

Return Values

• NU_SUCCESS

No errors with buffer or segment IDs

• ZC_INVALID_BUF_ID

Buffer ID is invalid

• ZC_BUF_SEG_MISMATCH

Segment ID/Buffer ID mismatched (segment not in buffer)

• ZC_BUF_EMPTY

Buffer is empty (segment specified for empty buffer)



ZC_BUF_EMPTY_CHECK

ZC_SEG_NONNULL_ENSURE

Component DescriptionsInput/Output Driver Component


Input/Output Driver ComponentThe input/output driver component (IO) is responsible for processing all Nucleus PLUSinput/output facilities. A Nucleus PLUS IO Driver Component provides a standard I/O driverinterface for initialization, assign, release, input, output, status, and terminate requests. Thisinterface is implemented with a common control structure. This enables applications to dealwith a variety of peripherals in a similar, if not the same manner. Tasks may suspend whilewaiting for a peripheral to become available. You can dynamically create and delete I/Odrivers. See the Nucleus PLUS Reference Manual for more detailed information aboutinput/output drivers.

Input/Output Driver FilesInput/Output Driver FilesThe IO consists of seven files. Each source file of the IO is defined in the following table.

Input/Output Data StructuresInput/Output Data Structures

Created Input/Output ListNucleus PLUS input/output drivers may be created and deleted dynamically. The Input/OutputControl Block (NU_DRIVER) for each created input/output driver is kept on a doubly linked,circular list. Newly created input/output drivers are placed at the end of the list, while deletedinput/output drivers are completely removed from the list. The head pointer of this list isIOD_Created_Drivers_List.

Table 4-59.

File Description

io_defs.h This file contains constants and data structure definitions specific tothe IO

io_extr.h All external interfaces to the IO are defined in this file

iod.c Global data structures for the IO are defined in this file

iof_established.c This file contains the information gathering functions for the IO

iof_pointers.c

ioc_common.c This file contains all of the core functions of the IO. Functions thathandle basic input and output services are defined in this file

ioce_common.c This file contains the error checking function interfaces for the corefunctions defined in ioc.c.



December 15, 2006

Figure 4-29. IOD Created Drivers List

Input/Output Driver Control BlockThe Input/Output Driver Control Block (NU_DRIVER) contains the entry function of thecurrent driver and other fields necessary for processing input/output driver requests.

Field Declarations

UNSIGNED words [NU_DRIVER_SIZE]CHAR nu_driver_name[NU_MAX_NAME]VOID *nu_info_ptrUNSIGNED nu_driver_idVOID (*nu_driver_entry)(struct NU_DRIVER_STRUCT*, NU_DRIVER_REQUEST *)

Field Summary

Created Input/Output List ProtectionNucleus PLUS protects the integrity of the Created Input/Output List from competing tasksand/or HISRs. This is done by using an internal protection structure called IOD_List_Protect.All input/output creation and deletion is done under the protection of IOD_List_Protect.

Table 4-60.

Field Description

words This is the link node structure for I/O drivers. It is linked into thecreated I/O driver’s list, which is a doubly linked, circular list.

nu_driver_name This is the user-specified, 8-character name for the I/O driver.

*nu_info_ptr A pointer to the user’s structure.

nu_driver_id This holds the internal I/O driver identification of 0x494F4452,which is an equivalent to ASCII IODR.

(*nu_driver_entry) This is the I/0 driver’s entry function.



Field Declarations


Field Summary

Total Input/Output DriversThe total number of currently created Nucleus PLUS input/output drivers is contained in thevariable IOD_Total_Drivers. The contents of this variable correspond to the number ofNU_DRIVERS on the created list. Manipulation of this variable is also done under theprotection of IOD_List_Protect.

Input/Output Driver Request StructureThe input/output driver request structure NU_DRIVER_REQUEST is responsible for passingnecessary information to and from a created I/O driver. The type of information in the request isspecified by the nu_function field in the request structure. Of course, the exact interpretation ofthis structure depends on the specific driver.

Field Declarations

INT nu_functionUNSIGNED nu_timeoutSTATUS nu_statusUNSIGNED nu_supplementalVOID nu_supplemental_ptrunion NU_REQUEST_INFO_UNION nu_request_info

Field Summary

Table 4-61.

Field Description

tc_tcb_pointer Identifies the thread that currently has the protection


Table 4-62.

Field Description

nu_function This is the I/O request function code. It can have one of 7 valuesdepending on which request is desired:

NU_INITIALIZE 1



December 15, 2006

Input/Output Driver Initialization RequestsI/O driver’s initialization requests are made using the initialization structure NU_INITIALIZE_STRUCT. This structure contains information about the driver’s base address and the driver’sinterrupt vector. This request is designated with an NU_INITIALIZE value in theNU_FUNCTION field of the NU_DRIVER_REQUEST.

Field Declarations

VOID *nu_io_addressUNSIGNED nu_logical_unitsVOID *nu_memoryINT nu_vector

Field Summary

NU_ASSIGN 2

NU_RELEASE 3

NU_INPUT 4

NU_OUTPUT 5

NU_STATUS 6

NU_TERMINATE 7

nu_timeout Holds the timeout on request.

nu_status Contains the status of the request.

nu_supplemental Contains user supplied supplemental information.

*nu_supplemental_ptr

A pointer to the driver specific supplemental information [optional].

nu_request_info A union of the structures that are used for driver requests. Theserequests include initialization, assign, release, input, output, status,and terminate.

Table 4-63.

Field Description

*nu_io_address A pointer to the base I/O address of the driver

nu_logical_unit Contains the number of logical units in the driver

*nu_memory A generic memory pointer

nu_vector Contains the interrupt vector number of the driver

Table 4-62. (cont.)

Field Description



Input/Output Driver Assignment RequestsI/O driver assignment requests are made using the NU_ASSIGN_STRUCT structure. Thisrequest is designated with an NU_ASSIGN value in the nu_function field of the NU_DRIVER_REQUEST structure.

Field Declarations

UNSIGNED nu_logical_unitINT nu_assign_info

Field Summary

Input/Output Driver Release RequestsI/O driver release requests are made using the NU_RELEASE_STRUCT structure. Thisrequest is designated with an NU_RELEASE value in the nu_function field of the NU_DRIVER_REQUEST structure.

Field Declarations

UNSIGNED nu_logical_unitINT nu_release_info

Field Summary

Input/Output Driver Input RequestsI/O driver inputs are made using the NU_INPUT_STRUCT structure. This structure containsinformation about data sent to the driver for processing. This request is designated with anNU_INPUT value in the nu_function field of the NU_DRIVER_REQUEST structure.

Table 4-64.

Field Description

nu_logical_unit Contains the I/O driver’s logical unit number

nu_assign_info This variable is used for additional I/O driver assign information

Table 4-65.

Field Description


nu_assign_info This variable is used for additional I/O driver release information



December 15, 2006

Field Declarations

UNSIGNED nu_logical_unitUNSIGNED nu_offsetUNSIGNED nu_request_sizeUNSIGNED nu_actual_sizeVoid *nu_buffer_ptr

Field Summary

Input/Output Driver Output RequestsI/O driver output requests are made using the NU_OUTPUT_STRUCT structure. Thisstructure contains information about data received from the driver. This request is designatedwith an NU_OUTPUT value in the nu_function field of the NU_DRIVER_REQUESTstructure.

Field Declarations

UNSIGNED nu_logical_unitUNSIGNED nu_offsetUNSIGNED nu_request_sizeUNSIGNED nu_actual_sizeVOID *nu_buffer_ptr

Field Summary

Table 4-66.

Field Description

nu_logical_unit Contains the I/O driver’s logical unit number.

nu_offset An I/O offset used as an offset from the device base I/O address or anoffset into the input buffer.

nu_request_size The requested size of the I/O driver input data.

nu_actual_size The actual size of the I/O driver input data.

*nu_buffer_ptr A pointer to the I/O driver input data buffer.

Table 4-67.

Field Description


nu_offset An I/O offset used as an offset from the device base I/O address or anoffset into the output buffer

nu_request_size The requested size of the I/O driver output data



Input/Output Driver Status RequestsI/O driver status requests are made using the NU_STATUS_STRUCT structure. This request isdesignated with an NU_STATUS value in the nu_function field of the NU_DRIVER_REQUEST_STRUCTURE structure.

Field Declarations

UNSIGNED nu_logical_unitVOID *nu_extra_status

Field Summary

Input/Output Driver Terminate RequestsI/O driver terminate requests are made using the NU_TERMINATE_STRUCTstructure. Thisrequest is designated with an NU_TERMINATE value in the nu_function field of the NU_DRIVER_REQUEST structure.

Field Declarations

UNSIGNED nu_logical_unit

Field Summary

nu_actual_size The actual size of the I/O driver output data

*nu_buffer_ptr A pointer to the IO driver output buffer

Table 4-68.

Field Description

nu_logical_units Contains the I/O driver’s logical unit number

*nu_extra_status A pointer to additional status information

Table 4-69.

Field Description

nu_logical_units Contains the I/O driver’s logical unit number

Table 4-67.

Field Description



December 15, 2006

Input/Output Driver FunctionsInput/Output DriverFunctions

The following sections provide a brief description of the functions in the IO. Review of theactual source code is recommended for further information.

Component DescriptionsIOC_Create_Driver


IOC_Create_DriverUsage

STATUS IOC_Create_Driver (NU_DRIVER *driver, CHAR *name, VOID*(driver_entry)(NU_DRIVER *, NU_DRIVER_REQUEST *))

Description

This function creates an I/O driver and places it on the list of created I/O drivers. Note that thisfunction does not actually invoke the driver.

Functions Called

CSC_Place_On_List


[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect


Component DescriptionsIOC_Delete_Driver

December 15, 2006

IOC_Delete_DriverUsage

STATUS IOC_Delete_Driver(NU_DRIVER *driver)

Description

This function deletes an I/O driver and removes it from the list of created drivers. Note that thisfunction does not actually invoke the driver.

Functions Called



[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsIOC_Request_Driver


IOC_Request_DriverUsage

STATUS IOC_Request_Driver (NU_DRIVER *driver, NU_DRIVER_REQUEST *request)

Description

This function sends a user request to the specified I/O driver.

Functions Called


[TCCT_Check_Stack]


Component DescriptionsIOC_Resume_Driver

December 15, 2006

IOC_Resume_DriverUsage

STATUS IOC_Resume_Driver (NU_TASK *task)

Description

This function resumes a task previously suspended inside an I/O driver. Typically, this functionis called from within an I/O driver.

Functions Called


TCC_Resume_Task


[TCCT_Check_Stack]



TCCT_System_Protect


TCCT_Unprotect


Component DescriptionsIOC_Suspend_Driver


IOC_Suspend_DriverUsage

STATUS IOC_Suspend_Driver (VOID (*terminate_routine)(VOID *), VOID *information,UNSIGNED timeout)

Description

This function suspends a task inside an I/O driver. It is the responsibility of the I/O driver tokeep track of tasks waiting inside an I/O driver.

Functions Called


TCC_Suspend_Task

TCCT_Current_Thread

[TCCT_Check_Stack]



TCCT_System_Protect



Component DescriptionsIOCE_Create_Driver

December 15, 2006

IOCE_Create_DriverUsage

STATUS IOCE_Create_Driver (NU_DRIVER *driver, CHAR *name, VOID (*driver_entry)(NU_DRIVER*,NU_DRIVER_REQUEST*))

Description

This function performs error checking on the parameters supplied to the I/O driver createfunction.

Functions Called

IOC_Create_Driver

Component DescriptionsIOCE_Delete_Driver


IOCE_Delete_DriverUsage

STATUS IOCE_Delete_Driver(NU_DRIVER *driver)

Description

This function performs error checking on the parameters supplied to the I/O driver deletefunction.

Functions Called

IOC_Delete_Driver


Component DescriptionsIOCE_Request_Driver

December 15, 2006

IOCE_Request_DriverUsage

STATUS IOCE_Request_Driver (NU_DRIVER *driver, NU_DRIVER_REQUEST *request)

Description

This function performs error checking on the parameters supplied to the I/O driver requestfunction.

Functions Called

IOC_Request_Driver

Component DescriptionsIOCE_Resume_Driver


IOCE_Resume_DriverUsage

STATUS IOCE_Resume_Driver (NU_TASK *task)

Description

This function performs error checking on the parameters supplied to the I/O driver resumefunction.

Functions Called

IOC_Resume_Driver

TCCE_Validate_Resume


Component DescriptionsIOCE_Suspend_Driver

December 15, 2006

IOCE_Suspend_DriverUsage

STATUS IOCE_Suspend_Driver (VOID (*terminate_routine) (VOID*), VOID *information,UNSIGNED timeout)

Description

This function performs error checking on the parameters supplied to the I/O driver suspendfunction.

Functions Called

IOC_Suspend_Driver

TCCE_Suspend_Error

Component DescriptionsIOF_Established_Drivers


IOF_Established_DriversUsage

UNSIGNED IOF_Established_Drivers (VOID)

Description

This function returns the current number of established I/O drivers. I/O drivers previouslydeleted are no longer considered established.

Functions Called

[TCCT_Check_Stack]


Component DescriptionsIOF_Driver_Pointers

December 15, 2006

IOF_Driver_PointersUsage

UNSIGNED IOF_Driver_Pointers (NU_DRIVER **pointer_list, UNSIGNEDmaximum_pointers)

Description

This function builds a list of driver pointers, starting at the specified location. The number ofdriver pointers placed in the list is equivalent to the total number of drivers or the maximumnumber of pointers specified in the call.

Functions Called

[TCCT_Check_Stack]

TCCT_Protect

TCCT_Unprotect

Component DescriptionsHistory Component (HI)


History Component (HI)The history component (HI) is responsible for processing all Nucleus PLUS History facilities.The Nucleus PLUS History Component maintains a circular log of various system activities.Application tasks and HISRs can make entries into the history log. Each entry in the history logcontains information about the particular Nucleus PLUS service call and the caller. See theNucleus PLUS Reference Manual for more detailed information about the History log.

History FilesThe HI consists of five files. Each source file of the History Component is defined in thefollowing table.

History Data Structures

History EnableNucleus PLUS History entries may be made dynamically. The History Enable flag indicateswhether or not history saving is enabled. If this value is NU_FALSE, history saving is disabled.Otherwise, history saving is enabled and an appropriate entry will be made in the history log asrequired.

Write IndexThe index of the next entry into the Nucleus PLUS History table is contained in the variableHID_Write_Index. The contents of this variable correspond to the location of the index of thenext available entry in the History table. Manipulation of this variable is also done under theprotection of HID_History_Protect.

Table 4-70.

File Description

hi_defs.h This file contains the constants and data structure definitions specificto the HI

hi_extr.h All external interfaces to the HI are defined in this file

hic_common.c This file contains all of the core functions of the HI. Functions thathandle basic enable-history-saving and disable-history-savingservices are defined in this file

hid.c Global data structures for the HI are defined in this file



December 15, 2006

Read IndexThe index of the oldest entry into the Nucleus PLUS History table is contained in the variableHID_Read_Index. The contents of this variable correspond to the location of the index of theoldest entry in the History table. Manipulation of this variable is also done under the protectionof HID_History_Protect.

History Table ProtectionNucleus PLUS protects the integrity of the History Table from competing tasks and/or HISRs.This is done by using an internal protection structure called HID_History_Protect. All Historyenabling and disabling is done under the protection of HID_History_Protect.

Field Declarations


Field Summary

Total EntriesThe total number of entries in the Nucleus PLUS History Table is contained in the variableHID_Entry_Count. The contents of this variable correspond to the number of valid entries inthe History table. Manipulation of this variable is also done under the protection of HID_History_Protect.

History Table StructureThe History Table Structure HI_History_Entry contains the starting index of the current historyentry and other fields necessary for processing History requests.

Field Declarations

DATA_ELEMENT hi_idDATA_ELEMENT hi_callerUNSIGNED hi_param1UNSIGNED hi_param2UNSIGNED hi_param3UNSIGNED hi_timeVOID *hi_thread

Table 4-71.

Field Declarations

tc_tcb_pointer Identifies the thread that currently had the protection




Field Summary

History FunctionsThe following sections provide a brief description of the functions in the HI. For furtherinformation, a review of the actual source code is recommended.

Table 4-72.

Field Description

hi_id This is the index in the table for History entries. It is a simple arrayconsisting only of HI_HISTORY_ENTRY structure.

hi_call The entity that made the entry into the History log. This can be a task,a HISR, or the initialization process

hi_param1 The first parameter for storing logged history information

hi_param2 The second parameter for storing logged history information

hi_param3 The third parameter for storing logged history information

hi_time The current system time in clock ticks

*hi_thread A pointer to the calling thread


Component DescriptionsHIC_Disable_History_Saving

December 15, 2006

HIC_Disable_History_SavingUsage

VOID HIC_Disable_History_Saving (VOID)

Description

This function disables the history saving function.

Functions Called

TCCT_Protect

TCCT_Unprotect

Component DescriptionsHIC_Enable_History_Saving


HIC_Enable_History_SavingUsage

VOID HIC_Enable_History_Saving (VOID)

Description

This function enables the history saving function.

Functions Called

TCCT_Protect

TCCT_Unprotect


Component DescriptionsHIC_Make_History_Entry_Service

December 15, 2006

HIC_Make_History_Entry_ServiceUsage

VOID HIC_Make_History_Entry_Service (UNSIGNED param1, UNSIGNED param2,UNSIGNED param3)

Description

This function makes an application entry in the history table.

Functions Called


Component DescriptionsHIC_Make_History_Entry


HIC_Make_History_EntryUsage

VOID HIC_Make_History_Entry (DATA_ELEMENT id, UNSIGNED param1, UNSIGNEDparam2, UNSIGNED param3)

Description

This function makes an entry in the next available location in the history table,(if history savingis enabled).

Functions Called

TCC_Current_HISR_Pointer

TCC_Current_Task_Pointer


TCCT_Protect


TCCT_Unprotect


TMCT_Retrieve_Clock


Component DescriptionsHIC_Retrieve_History_Entry

December 15, 2006

HIC_Retrieve_History_EntryUsage

STATUS HIC_Retrieve_History_Entry (DATA_ELEMENT*id, UNSIGNED *param1,UNSIGNED *param2, UNSIGNED *param3, UNSIGNED *time, NU_TASK **task,NU_HISR **hisr)

Description

This function retrieves the next oldest entry in the history table. If no more entries are available,an error status is returned.

Functions Called

TCCT_Protect

TCCT_Unprotect

Component DescriptionsError Component (ER)


Error Component (ER)The error component (ER) is responsible for processing all Nucleus PLUS System Errors. TheNucleus PLUS Error Component is a common error handling function that handles fatal system-error conditions. System processing is transferred to this component when a fatal error occurs.The function then creates an appropriate ASCII error message. This serves to inform you aboutthe type of error. The system is then trapped by an infinite loop. See the Nucleus PLUSReference Manual for more detailed information about Error Management.

Error FilesThe ER consists of four files. Each source file of the ER is defined in the following table.

Error Data Structures

Error CodesNucleus PLUS errors are detected through the use of error codes. When the system determinesan error condition exists, it determines the type of error through the use of an error code. Theerror code value is placed in the variable ERD_Error_Code. Nucleus PLUS error codes arelisted in the following table.

Table 4-73.

File Description

er_extr.h All external interfaces to the ER are defined in this file

erc_common.c This file contatins the core function of the ER. The function thathandles the basic system error service is defined in this file

erd.c Global data structures for the ER are defined in this file

Table 4-74.

Code Constant Description

1 NU_ERROR_CREATING_TIMER_HISR

An error occurred creating the timer HISR

2 NU_ERROR_CREATING_TIMER_TASK

An error occurred creating the timer task

3 NU_STACK_OVERFLOW

A task or HISR stack overflow occurred


Component DescriptionsError Component (ER)

December 15, 2006

Error FunctionsThe following sections provide a brief description of the functions in the ER. Review of theactual source code is recommended for further information.

4 NU_UNHANDLED_INTERRUPT

An interrupt occurred prior to a LISR registration

5 NU_NOT_IN_SUPERVISOR_MODE

A thread in user mode attempted to executesomething that requires supervisor mode

6 NU_NOT_ENOUGH_DTLBS

Not enough data translation look-aside buffersavailable

7 NU_NOT_ENOUGH_ITLBS

Not enough intruction translation look-asidebuffers available

8 NU_STACK_UNDERFLOW

A task or HISR stack underflow occurred

9 NU_UNHANDLED_EXCEPTION

An exception occurred that does not have aregistered handler

Table 4-74. (cont.)

Code Constant Description

Component DescriptionsERC_System_Error


ERC_System_ErrorUsage

VOID ERC_System_Error (INT error_code)

Description

This function processes system errors detected by various system components. Typically anerror of this type is considered fatal.


Component DescriptionsERC_Assert

December 15, 2006

ERC_AssertUsage

VOID ERC_Assert (CHAR *test, CHAR *name, UNSIGNED line)

Description

This function increments the global variable ERD_Assert_Count. It is called by the NU_Assertmacro. If history logging is enabled the passed in filename and line number are recorded.

Component DescriptionsERC_Assert


Error MacrosError FunctionsThe following sections provide a brief description of the macros in the ER. These macros areonly defined if NU_DEBUG_ENABLE is defined to NU_TRUE. Review of the actual sourcecode is recommended for further information.


Component DescriptionsNU_ASSERTERC_System_Error

December 15, 2006

NU_ASSERTERC_System_ErrorDescription

This macro checks to see if the test is true. When the test is false, a call to ERC_Assert is made.

Component DescriptionsNU_CHECKERC_System_Error


NU_CHECKERC_System_ErrorDescription

This macro checks to see if the test is true. When the test is false, the passed in statement isexecuted.


Component DescriptionsRelease Component (RL)

December 15, 2006

Release Component (RL)The release component (RL) is responsible for processing all Nucleus PLUS release facilities.The Nucleus PLUS release component is a function that is dedicated to storing and reportingrelease information. This information includes the current version and release number of theNucleus PLUS software. See the Nucleus PLUS Reference Manual for more detailedinformation about release management.

Release FilesThe RL consists of two files. Each source file of the RL is defined in the following table.

Release Data Structures

Release InformationNucleus PLUS reports release versions in the form of unsigned integer values. These values arestored in the variables RLD_Major_Version and RLD_Minor_Version. The RLD_Major_Version variable contains the current major release of the Nucleus PLUS software. The RLD_Minor_Version variable contains the current minor release of the Nucleus PLUS software. Notarget specific information is kept in the release information.

Release FunctionsThe following sections provide a brief description of the functions in the RL. For furtherinformation, a review of the actual source code is recommended.

Table 4-75.

File Description

rl_extr.h This file contains prototypes for the RL component.

rlc_common.c This file contains the core function of the RL. The function thathandles the basic system release reporting service is defined in thisfile.

rld.c Global data structures for the RL are defined in this file.

Component DescriptionsRLC_Initialize


RLC_InitializeUsage

VOID RLC_Initialize (VOID)

Description

This function initializes the variables that store the release major and minor versions.

Functions Called

RLC_Get_Version


Component DescriptionsRLC_Get_Version

December 15, 2006

RLC_Get_VersionUsage

VOID *RLC_Get_Version (UINT* major, UINT* minor)

Description

This function retrieves the major and minor release versions. This identifies the current versionof Nucleus PLUS.

Component DescriptionsRLC_Get_Version


Release Macros Error FunctionsThe following sections provide a brief description of the macros in the RL.


Component DescriptionsPLUS_RELEASE_STRING

December 15, 2006

PLUS_RELEASE_STRINGDescription

This macro returns the Nucleus PLUS release string.


Chapter 5ESAL Component

IntroductionEmbedded Software Abstraction Layer (ESAL) is a software layer that interfaces an OperatingSystem Kernel with its target hardware and toolset. ESAL encapsulates the target dependentcode needed by the Kernel. This makes the Kernel easier to implement and understand. Real-time applications are linked with the OS Kernel and ESAL libraries to build an executableprogram image.

Figure 5-1. ESAL

ESAL File Naming ConventionESAL file names conform to the following naming convention:

Table 5-1.

File Purpose

esal_entry.c *(esal_entry_a.<s>) This special purpose file provides the entry pointinto the ESAL code that executes after hardwarepower up or reset. This entry point is generallyimplemented in assembly language.

esal_extern.h This file makes available the external functioninterfaces of the ESAL components.

esal_<xx>_cfg.h This type of file contains componentconfiguration settings. Other components mayrefer to these settings.


ESAL ComponentESAL File Naming Convention

December 15, 2006

* Due to architectural and performance requirements, some of the functions in this file arenormally written in the processor’s native assembly language. Therefore, there may anassembly language file in addition to (or as a replacement for) this C file. In addition, anynecessary constants will be found in a corresponding assembly language include file (*.inc).

ESAL file names generally take the form:

esal_<component>_<functional_area>[_defs].<ext>

esal_<xx>_<yyy>_defs.h(esal_<xx>_<yyy>_defs.inc)

This type of file defines component constants anddata structures.

esal_<xx>_<yyy>.c(esal_<xx>_<yyy>_a.<s>)

This type of file contains component functions.

Table 5-2.

Component names (<component>) can be:

ge – Generic Component

ts – Toolset Specific Component

ar – Architecture Specific Component

co – Core Specific Component

pr – Processor Specific Component

dp – Development Platform Specific Component

Table 5-3.

Functional area (<functional_area>) can be:

cfg – Configuration

com – Common

int – Interrupt Control

isr – Interrupt Servicing

mem – Memory

rte – Run-Time Environment

stk – Stack

Table 5-1. (cont.)

File Purpose

ESAL ComponentESAL File Naming Convention


The following example illustrates this convention as used in the files of the ESAL genericcomponent.

Example

esal_ge_cfg.h

esal_ge_com_defs.h

esal_ge_int_defs.h

esal_ge_isr_defs.h

esal_ge_mem_defs.h

esal_ge_rte_defs.h

esal_ge_stk_defs.h

esal_ge_tmr_defs.h

esal_ge_int.c

esal_ge_isr.c

esal_ge_mem.c

esal_ge_rte.c

esal_ge_stk.c

esal_ge_tmr.c

tmr – Timer

Table 5-4.

File name extenstion (<ext>) can be:

c - C source

h - C Include

inc - Assembly Include

<s> - Assembly Source. The extension is usually toolset specific.

Table 5-3. (cont.)

Functional area (<functional_area>) can be:


ESAL ComponentComponents

December 15, 2006

ComponentsESAL code is divided into different components to enhance clarity, modularity, reliability,reusability, and ease of maintenance. Each of the ESAL components has a unique purpose and aspecific external interface to other components.

Figure 5-2. ESAL Components

The ESAL components are as follows:

• Generic Component (GE) – This contains the functions which do not require anymodifications for different target environments. The configuration settings may bemodified. The generic component does not contain any target specific functions, but cancall target specific functions.

• Toolset Specific Component (TS) – This contains the files and functions that must bemodified in order to accommodate the requirements imposed by the toolset (i.e.compiler, assembler, librarian, and linker) being used to develop for a given targetenvironment.

• Architecture Specific Component (AR) – This contains the files and functions thatmust be modified in order to accommodate the requirements imposed by (or to utilizefeatures provided by) the microprocessor architecture selected for a given targetenvironment. An architecture is the common specification for all microprocessors of agiven type.

The list below provides an example of several microprocessor architectures:

o PPC

o ARM

o MIPS32

ESAL ComponentComponents


• Core Specific Component (CO) – This contains the files and functions that must bemodified in order to accommodate the requirements imposed by (or to utilize featuresprovided by) the microprocessor core selected for a given target environment. A core isa particular variant (implementation) of the given architecture and can be a subset orsuperset of the architecture’s specification.

The list below provides an example of several microprocessor cores:

o G2 - has a PPC architecture

o ARM920T - has an ARM architecture

o Au1 - has a MIPS32 architecture

• Processor Specific Component (PR) – This contains the files and functions that mustbe modified in order to accommodate the requirements imposed by (or to utilize featuresprovided by) the processor selected for a given target environment. A processor is a coreand supporting peripherals on a single form factor.

The list below provides an example of several processors:

o MPC5200 - has a G2 core with a PPC architecture

o CM920T - has an ARM920T core with an ARM architecture

o Au1100 – has an AU1 core with an MIPS32 architecture

• Development Platform Specific Component (DP) – This contains the files andfunctions that must be modified in order to accommodate the requirements imposed by agiven development platform. A development platform is a board that may containadditional peripherals that interface to the processor.

The list below provides an example of several development platforms:

o Freescale Lite 5200 – has a MPC5200 processor

o ARM Integrator/CP – has an CM920T processor

o DBAu1100 – has an Au1100 processor

Figure 5-3. Abstract View of ESAL Hardware Components


ESAL ComponentComponent Functional Areas

December 15, 2006

Figure 5-4. Example of ESAL Hardware Components

Component Functional AreasEach ESAL components provide APIs for one or more functional areas. The component namedescribes the target (generic, hardware, or toolset) of the code. The name of the ESALfunctional area describes what the code does.



Figure 5-5. ESAL Component Functional Areas



December 15, 2006

The ESAL functional areas are as follows:

• Common (com) – This functional area provides common ESAL defines, structures, datatypes, etc., for all ESAL components. It consists of the esal_ge_com_defs.h header file.

• Configuration (cfg) – This functional area configures the behavior of each ESALcomponent. This is done through the setting of defines in each ESAL component’sconfiguration header file (esal_<component>_cfg.h).

• Debug (dbg) - This functional area provides defines and functions that enable run-timedebugging information to be extracted from internal ESAL data structures and variables.

• Interrupt Control (int) – This functional area controls interrupts by reading from andwriting to the interrupt registers and controllers of the individual ESAL hardwarecomponents. This includes enabling, disabling, setting, and getting interrupts.

• Interrupt Servicing (isr) – This functional area provides the framework and code forprocesses interrupts and exceptions. This includes calling and returning from interruptand exception handlers. This also includes implementing the hardware’s vector tableand interfacing with the OS’s specific scheduling and interrupt functions.

• Memory (mem) – This functional area provides basic memory related operations. Thisincludes initializing hardware for memory access, enabling caching, and managing basicinformation on memory regions. This also includes functions that prepare a C run-timeenvironment, such as for clearing BSS and copying initialized data from ROM to RAM.

• Run-time Environment (rte) – This functional area provides basic initialiazation of theC run-time environment as required by the given toolset. This includes calling memoryoperations to clear BSS and copy initialized data from ROM to RAM. This also includeshooks for assembly level initialization of the RTE and for application-specific needs.

• Stack (stk) – This functional area provides operations for managing execution threadstacks. This includes saving and restoring solicited (toolset) and unsolicted(architecture) stack frames. This also includes creating an execution thread’s initialstack.

A solicted stack frame is created as a result of a solicited context switch (which occursduring normal execution thread scheduling).. An unsolicited stack frame is created as aresult of an unsolicited context switch (which occurs during interrupt and exceptionhandling)

• OS Timer (tmr) – This functional area provides operations for managing an OS timer.This includes initializing a hardware timer to generate interrupts on a periodic basis, andregistering an OS specific handler to service these timer interrupts.

ESAL ComponentGeneric Component (GE)


Generic Component (GE)The ESAL generic component (GE) is responsible for providing defines, structures, data types,etc., that are common to all ESAL components. The generic files contain completely generic Ccode. No target dependent code exists in these files, but calls are made to functions contained inother ESAL components that do contain target dependent code.

Generic Component FilesThe ESAL generic component consists of the files defined in the following table.

Table 5-5.

File Description

esal_extern.h * This file defines the external interfaces to theESAL components

esal_ge_cfg.h This file contains required configurationsettings generic to all components of ESAL.Other components may refer to thesesettings

esal_ge_com_defs.h This file contains generic defines, structures,data types, and so on, common to all ESALcomponents

esal_ge_dbg_defs.h This file contains generic defines, structures,data types, etc related to debugging.

esal_ge_int_defs.h This file contains generic defines, structures,data types, and so on, related to interruptcontrol

esal_ge_isr_defs.h This file contains generic defines, structures,data types, and so on, related to interruptservicing

esal_ge_mem_defs.h This file contains generic defines, structures,data types, and so on, related to memory

esal_ge_rte_defs.h This file contains generic defines, structures,data types, and so on, related to run-timeenvironment requirements

esal_ge_stk_defs.h This file contains generic defines, structures,data types, and so on, related to stacks

esal_ge_tmr_defs.h This file contains generic defines, structures,data types, and so on, related to timers



December 15, 2006

* The esal_extern.h file does not belong to a specific ESAL component, but is required for allports that incorporate ESAL. This file resides in the root directory of the ESAL component andprovides the external interface (API) to the ESAL components. Therefore, this file is describedwith the ESAL generic files.

Generic Component Data Structures

OS Entry Point for Interrupt Service RoutinesESAL will process interrupts. In doing so it will call the OS’s common interrupt servicingfunction. The ESAL_GE_ISR_OS_Entry variable is set to be this OS specific function. See theESAL_GE_ISR_Initialize function.

OS Entry Point for Nested Interrupt Service RoutinesESAL will process nested interrupts. In doing so it will call the OS’s common nested interruptservicing function. The ESAL_GE_ISR_OS_Nested_Entry variable is set to be this OS specificfunction. See the ESAL_GE_ISR_Initialize function.

Interrupt Handlers and Interrupt Vector IDsESAL defines a common array of pointers to functions that handle each specific interrupt. Thisarray, or dispatch table, is called ESAL_GE_ISR_Interrupt_Handler. It is used whendispatching a particular interrupt. The contents of the array is grouped by component. Pointers

esal_ge_dbg.c This file contains generic functions relatedto debugging.

esal_ge_int.c This file contains generic functions relatedto interrupt control

esal_ge_isr.c This file contains generic functions relatedto interrupt servicing

esal_ge_mem.c This file contains generic functions relatedto memory

esal_ge_rte.c This file contains generic functions relatedto run-time environment requirements

esal_ge_stk.c This file contains generic functions relatedto stacks

esal_ge_tmr.c This file contains generic functions relatedto timers

Table 5-5. (cont.)

File Description



to handlers for architecture interrupts occupy the first entries in the table, followed by those forprocessor interrupts (if any), followed by those for development platform interrupts (if any).

NoteThe OS Kernel is responsible for providing a function that allows applications to registera handler. The OS can use the macro ESAL_GE_ISR_HANDLER_SET within itsfunction, where the argument to ESAL_GE_ISR_HANDLER_SET is the vector ID.

An interrupt vector ID is defined for each interrupt source. The interrupt vector ID is an indexinto the interrupt dispatch table. The INT definitions files (esal_<component>_int_defs.h)define the valid interrupt vector IDs for a given target.

An interrupt vector ID only corresponds to the index of the interrupt’s handler inESAL_GE_ISR_Interrupt_Handler. This does not necessarily correspond to the interrupt’s“number “ as defined by the target hardware

Figure 5-6. ESAL_GE_ISR_Interrupt_Handler

The Figure 5-6 shows delimiters defined to mark one past the last vector of the AR, PR, and DPcomponents. Notice the following:

• The value of the last delimiter (ESAL_DP_INT_VECTOR_ID_DELIMITER) is equalto the total number of interrupt handlers in ESAL_GE_ISR_Interrupt_Handler.

• The value of the first PR interrupt vector ID is equal to the value of the AR interruptvector ID delimiter (ESAL_AR_INT_VECTOR_ID_DELIMITER).

• The value of the first DP interrupt vector ID is equal to the value of the PR interruptvector ID delimiter (ESAL_PR_INT_VECTOR_ID_DELIMITER).



December 15, 2006

• When there are no PR interrupts, ESAL_PR_INT_VECTOR_ID_DELIMITER is equalto ESAL_AR_INT_VECTOR_ID_DELIMITER.

• When there are no DP interrupts, ESAL_DP_INT_VECTOR_ID_DELIMITER is equalto (ESAL_PR_INT_VECTOR_ID_DELIMITER.

• Every implementation of ESAL will define ESAL_AR_INT_VECTOR_ID_DELIMITER , ESAL_PR_INT_VECTOR_ID_DELIMITER, and ESAL_DP_INT_VECTOR_ID_ DELIMITER even if there are no interrupt sources at each of theselevels of abstraction.

Interrupt Service Routine is ExecutingThe variable ESAL_GE_ISR_Executing is used to track whether ESAL is in the process ofhandling an interrupt. It is primarily used to detect when interrupts are nesting.

Exception Handlers and Exception Vector IDsESAL defines a common array of pointers to functions that handle each specific exception. Thisarray, or dispatch table, is called ESAL_GE_ISR_Exception_Handler. It is used whendispatching a particular exception.

An exception vector ID is defined for each exception source. The exception vector ID is anindex into the exception handler table. The ISR definitions files, esal_ar_int_defs.h, defines thevalid exception vector IDs for a given target.

An exception vector ID only corresponds to the index of the exception’s handler inESAL_GE_ISR_Exception_Handler. This does not necessarily correspond to the exception’s“number “ as defined by the target hardware

Figure 5-7. ESAL_GE_ISR_Exception_Handler

The Figure 5-7 shows the delimiter defined to mark one past the last vector. Notice that thevalue of the delimiter (ESAL_AR_INT_VECTOR_ID_DELIMITER) is equal to the totalnumber of exception handlers in ESAL_GE_ISR_Exception_Handler.



Memory RegionESAL may use memory region descriptions for various purposes. Each memory region isdescribed by a structure called ESAL_GE_MEM_REGION. The actual memory regions aredescribed by the array ESAL_DP_MEM_Region_Data described later in this chapter.

Field Declarations

VOID *physical_start_addr;VOID *virtual_start_addr;UINT32 size;ESAL_GE_CACHE_TYPE cache_type;ESAL_GE_MEMORY_TYPE mem_type;ESAL_GE_MEMORY_ACCESS access_type;

Field Summary

System Stack MemoryThe system stack memory comes from the array called ESAL_GE_STK_System_SP_Memory.This stack will also be used when servicing interrupts.

Pointer to the Start of the System StackThe start address of the system stack may need to be aligned properly for a given architecture.The variable ESAL_GE_STK_System_SP is initialized to be a properly aligned address for thesystem stack. This variable is set once and never changed.

Exception Stack MemoryThe exception stack memory comes from the array called ESAL_GE_STK_Except_SP_Memory. This stack will be used when servicing exceptions.

Table 5-6.

Field Description

physical_start_addr Starting physical address

virtual_start_addr Starting virtual address

size Size of region in bytes

cache_type Type of caching for this memory region (see ESAL_GE_CACHE_TYPE)

mem_type Type of memory region (see ESAL_GE_MEMORY_TYPE)

access_type Type of access for this memory region (seeESAL_GE_ MEMORY_ACCESS)



December 15, 2006

Pointer to the Start of the Exception StackThe start address of the exception stack may need to be aligned properly for a givenarchitecture. The variable ESAL_GE_STK_Except_SP is initialized to be a properly alignedaddress for the exception stack. This variable is set once and never changed.

OS Entry Point for Unsolicited Execution Thread SwitchingESAL calls the OS’s entry point for unsolicited thread switching whenever an interrupt occursthat causes a context switch. The variable ESAL_GE_STK_Unsol_Switch_OS_Entry is set tobe this OS specific entry point and will be called after the context of the current thread is saved.See the function ESAL_GE_STK_Initialize.

Unsolicited Execution Thread Switch Is RequiredThe OS’s interrupt handling code informs the ESAL interrupt code that an unsolicted contextswitch is required. The variable ESAL_GE_STK_Unsol_Switch_Req is used for this purpose.

Generic Component FunctionsThe following sections provide a brief description of the functions in the generic component.Review of the actual source code is recommended for further information.

ESAL ComponentESAL_GE_DBG_Initialize


ESAL_GE_DBG_InitializeUsage

VOID ESAL_GE_DBG_Initialize(VOID **(*brk_handler)(VOID *))

Description

This function initializes the debugging components.

This function performs the following steps:

• Calls the ESAL_AR_DBG_Initialize function

• Tests if the DBG Break Handler exists and if so sets it as the default Debug BreakException Handler.

Functions Called

ESAL_AR_DBG_Initialize


ESAL ComponentESAL_GE_DBG_Default_Brk_Handler

December 15, 2006

ESAL_GE_DBG_Default_Brk_HandlerUsage

VOID ESAL_GE_DBG_Initialize(VOID **(*brk_handler)(VOID *))

Description

This function is the default Debug Break Exception Handler.

This function just spins in an endless loop.

Functions Called

None.

ESAL ComponentESAL_GE_INT_All_Disable


ESAL_GE_INT_All_DisableUsage

VOID ESAL_GE_INT_All_Disable (VOID)

Description

This function calls the disable interrupt function in each configured component to disable allinterrupt sources. The configuration settings in esal_dp_cfh.h and esal_pr_cfg.h determinewhich functions are called.

Functions Called

[ESAL_DP_INT_All_Disable]

[ESAL_PR_INT_All_Disable]


ESAL ComponentESAL_GE_INT_Global_Set

December 15, 2006

ESAL_GE_INT_Global_SetUsage

INT ESAL_GE_INT_Global_Set (INT new_value)

Description

This function uses architecturally specific macros to enable or disable interrupts to a specifiedlevel. Calls are made to get the current interrupt level and then to set the interrupt level to thepassed in value.

Functions Called

ESAL_AR_INT_BITS_GET

ESAL_AR_INT_BITS_SET

ESAL ComponentESAL_GE_INT_Enable


ESAL_GE_INT_EnableUsage

VOID ESAL_GE_INT_Enable (INT vector_id, ESAL_GE_INT_TRIG_TYPE trigger_type,INT priority)

Description

This function calls the enable interrupt function in the appropriate component to enable thegiven interrupt source with the specified attributes. The configuration settings in esal_dp_cfg.hand esal_pr_cfg.h in conjunction with the architecture vector IDs defined in esal_ar_int_defs.hdetermine which functions are called.

Functions Called

[ESAL_AR_INT_Enable]

[ESAL_DP_INT_Enable]

[ESAL_PR_INT_Enable]


ESAL ComponentESAL_GE_INT_Disable

December 15, 2006

ESAL_GE_INT_DisableUsage

VOID ESAL_GE_INT_Disable (INT vector_id)

Description

This function calls the disable interrupt function in the appropriate component to disable thegiven interrupt source. The configuration settings in esal_dp_cfg.h and esal_pr_cfg.h inconjunction with the architecture vector IDs defined in esal_ar_int_defs.h determine whichfunctions are called.

Functions Called

[ESAL_AR_INT_Disable]

[ESAL_DP_INT_Disable]

[ESAL_PR_INT_Disable]

ESAL ComponentESAL_GE_ISR_Default_Exc_Handler


ESAL_GE_ISR_Default_Exc_HandlerUsage

static VOID ESAL_GE_ISR_Default_Exc_Handler(INT except_vector_id, VOID *stack_ptr)

Description

This function is the default exception handler for all exceptions supported by the givenarchitecture.


ESAL ComponentESAL_GE_ISR_Default_Int_Handler

December 15, 2006

ESAL_GE_ISR_Default_Int_HandlerUsage

static VOID ESAL_GE_ISR_Default_Int_Handler (INT int_vector_id)

Description

This function is the default interrupt handler for all interrupts supported by the givenarchitecture, processor, and development platform. This function is assigned to all interruptvectors if the ESAL_GE_ISR_Initialize function is called with the *default_isr parameter setto NULL. In addition, ESAL_GE_ISR_Default_Int_Handler is used as the ESAL_GE_ISR_OS_Nested_Entry ISR if the ESAL_GE_ISR_Initialize function is called with the *os_nested_isr_entry parameter set to NULL.

ESAL ComponentESAL_GE_ISR_Initialize


ESAL_GE_ISR_InitializeUsage

VOID ESAL_GE_ISR_Initialize (VOID (*default_isr)(INT), VOID (*default_except)(INT,VOID *), VOID **(*os_isr_entry)(INT, VOID *), VOID (*os_nested_isr_entry)(INT))

Description

This function performs the necessary ISR initialization for each ESAL component, asconfigured in each component’s configuration files. The input parameters are used to overridethe default ESAL interrupt handlers. The input parameters should be OS specific interrupthandlers. The function pararmeters correspond to the default interrupt service routine for allinterrupts, the default exception handler for all exceptions, the common handler for allinterrupts, and the common handler for all nested interrupts.

Functions Called

ESAL_GE_ISR_HANDLER_SET

ESAL_AR_ISR_Vector_Table_Install

[ESAL_AR_ISR_Initialize]

[ESAL_PR_ISR_Initialize]

[ESAL_DP_ISR_Initialize]


ESAL ComponentESAL_GE_ISR_OS_Default_Entry

December 15, 2006

ESAL_GE_ISR_OS_Default_EntryUsage

static VOID **ESAL_GE_ISR_OS_Default_Entry (INT vector, VOID *stack_ptr)

Description

This function is the default ESAL ISR entry point for the system. This function is used as theESAL_GE_ISR_OS_Entry ISR if the ESAL_GE_ISR_Initialize function is called with the*os_isr_entry parameter set to NULL.

ESAL ComponentESAL_GE_ISR_OS_RETURN


ESAL_GE_ISR_OS_RETURNUsage

VOID ESAL_GE_ISR_OS_RETURN (VOID (*os_return_func_ptr)(VOID))

Decription

This macro is used by the OS at the end of interrupt handling (from ESAL_GE_ISR_OS_Entry)to return back into an OS function instead of returning to the point of interrupt. The ESAL_AR_ISR_RTI_MANDATORY configuration setting in esal_ar_cfg.h determines how this macrobehaves. The configuration setting is enabled on architectures that mandate a "return frominterrupt" (RTI) instruction in order for the hardware to correctly restore the state of execution.

When the setting is disabled, this macro simply calls the OS return function. When the setting isenabled this macro calls ESAL_AR_ISR_Return to perform the necessary operations.


ESAL ComponentESAL_GE_MEM_Clear

December 15, 2006

ESAL_GE_MEM_ClearUsage

VOID ESAL_GE_MEM_Clear (VOID *start, UINT32 size)

Description

This function writes zeros to the specified number of memory bytes starting at the passed inaddress. The configuration setting ESAL_GE_OPTIMIZE_SIZE is used to determine if thisfunction is optimized for size or speed.

ESAL ComponentESAL_GE_MEM_Copy


ESAL_GE_MEM_CopyUsage

VOID *ESAL_GE_MEM_Copy (VOID *dst, const VOID *src, UINT32 size)

Description

This function copies a block of memory, of the specified size, from the specified source addressto the specified destination address. The configuration setting ESAL_GE_OPTIMIZE_SIZE isused to determine if this function is optimized for size or speed.


ESAL ComponentESAL_GE_MEM_Set

December 15, 2006

ESAL_GE_MEM_SetUsage

VOID ESAL_GE_MEM_Set (VOID *dest, INT value, INT size)

Description

This function sets a block of memory to the specified value from the specified start address forthe specified size.

ESAL ComponentESAL_GE_MEM_Initialize


ESAL_GE_MEM_InitializeUsage

VOID *ESAL_GE_MEM_Initialize (VOID)

Description

This function initializes all required target memory components. The function ESAL_TS_MEM_First_Avail_Get is called to obtain the starting address of available memory. In addition,the configuration settings ESAL_CO_CACHE_AVAILABLE and ESAL_PR_CACHE_AVAILABLE determine if the respective cache enable functions are executed.

Functions Called

ESAL_TS_MEM_First_Avail_Get

[ESAL_CO_MEM_Cache_Enable]

[ESAL_PR_MEM_Cache_Enable]


ESAL ComponentESAL_GE_MEM_CACHE_ALL_INVALIDATE

December 15, 2006

ESAL_GE_MEM_CACHE_ALL_INVALIDATEUsage

VOID ESAL_GE_MEM_CACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all cache (instruction and data) within the configured components.

Functions Called

[ESAL_CO_MEM_CACHE_ALL_INVALIDATE]

[ESAL_PR_MEM_CACHE_ALL_INVALIDATE]

ESAL ComponentESAL_GE_MEM_CACHE_ALL_INVALIDATE


ESAL_GE_MEM_CACHE_ALL_INVALIDATEUsage

VOID ESAL_GE_MEM_CACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidate all instruction cache within the configured components.

Functions Called

[ESAL_CO_MEM_CACHE_ALL_INVALIDATE]

[ESAL_PR_MEM_CACHE_ALL_INVALIDATE]


ESAL ComponentESAL_GE_MEM_DCACHE_ALL_INVALIDATE

December 15, 2006

ESAL_GE_MEM_DCACHE_ALL_INVALIDATEUsage

VOID ESAL_GE_MEM_DCACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all data cache within the configured components.

Functions Called

[ESAL_CO_MEM_DCACHE_ALL_INVALIDATE]

[ESAL_PR_MEM_DCACHE_ALL_INVALIDATE]

ESAL ComponentESAL_GE_MEM_ICACHE_INVALIDATE


ESAL_GE_MEM_ICACHE_INVALIDATEUsage

VOID ESAL_GE_MEM_ICACHE_INVALIDATE (VOID *addr, UINT32 size)

Description

This macro invalidates the instruction cache for the specified address range within theconfigured components.

Functions Called

[ESAL_CO_MEM_ICACHE_INVALIDATE]

[ESAL_PR_MEM_ICACHE_INVALIDATE]


ESAL ComponentESAL_GE_MEM_DCACHE_INVALIDATE

December 15, 2006

ESAL_GE_MEM_DCACHE_INVALIDATEUsage

VOID ESAL_GE_MEM_DCACHE_INVALIDATE (VOID *addr, UINT32 size)

Description

This macro invalidates the data cache for the specified address range within the configuredcomponents.

Functions Called

[ESAL_CO_MEM_DCACHE_INVALIDATE]

[ESAL_PR_MEM_DCACHE_INVALIDATE]

ESAL ComponentESAL_GE_MEM_DCACHE_ALL_FLUSH_INVAL


ESAL_GE_MEM_DCACHE_ALL_FLUSH_INVALUsage

VOID ESAL_GE_MEM_DCACHE_ALL_FLUSH_INVAL (VOID)

Description

This macro writes all data cache to physical memory and invalidates all data cache within theconfigured components.

Functions Called

[ESAL_CO_MEM_DCACHE_ALL_FLUSH_INVAL]

[ESAL_PR_MEM_DCACHE_ALL_FLUSH_INVAL]


ESAL ComponentESAL_GE_MEM_DCACHE_FLUSH_INVAL

December 15, 2006

ESAL_GE_MEM_DCACHE_FLUSH_INVALUsage

VOID ESAL_GE_MEM_DCACHE_FLUSH_INVAL (VOID *addr, UINT32 size)

Description

This macro writes data cache to physical memory for the specified address range and invalidatesthis data cache within the configured components.

Functions Called

[ESAL_CO_MEM_DCACHE_FLUSH_INVAL]

[ESAL_PR_MEM_DCACHE_FLUSH_INVAL]

ESAL ComponentESAL_GE_MEM_Next_Match_Find


ESAL_GE_MEM_Next_Match_FindUsage

VOID *ESAL_GE_MEM_Next_Match_Find (VOID *start_addr, ESAL_GE_CACHE_TYPEcache_type, ESAL_GE_MEMORY_TYPE mem_type, UINT32 access_type)

Description

This function finds the next memory region (as described by ESAL_DP_MEM_Region_Data)matching the memory type, memory cache type, and access type starting from the specifiedaddress. The start address of a region matching these criteria is returned to the caller. If memorymatching these criteria is not found, an error value is returned to the caller.

If the region containing the start address matches the requested attributes, the start address willbe returned to the caller

This function is included in the ESAL library only if the conditional below, contained inesal_ge_cfg.h, is defined as ESAL_TRUE.

ESAL_GE_MEM_UTIL_INCLUDE


ESAL ComponentESAL_GE_MEM_Region_Addr_Search

December 15, 2006

ESAL_GE_MEM_Region_Addr_SearchUsage

VOID *ESAL_GE_MEM_Region_Addr_Search (VOID *start_addr,ESAL_GE_MEM_REGION **mem_region, VOID **region_end)

Description

This function searches for a particular start address in all the memory regions described byESAL_DP_MEM_Region_Data. If a region is found containing the start address, a pointer tothis region is returned to the caller along with the end address of this region.



ESAL ComponentESAL_GE_MEM_Remaining_Size_Get


ESAL_GE_MEM_Remaining_Size_GetUsage

UINT32 ESAL_GE_MEM_Remaining_Size_Get (VOID *start_addr)

Description

This function gets the remaining memory size, in bytes, starting at the specified start addressand up to the end of the containing memory region described by ESAL_DP_MEM_Region_Data.



Functions Called

ESAL_GE_MEM_Region_Addr_Search


ESAL ComponentESAL_GE_RTE_Initialize

December 15, 2006

ESAL_GE_RTE_InitializeUsage

VOID ESAL_GE_RTE_Initialize (VOID)

Decription

This function initializes the run-time environment as required for a given toolset. It performsRTE initialization by calling the three functions listed below. Note that the functions are calledunconditionally. If the toolset does not require that particular initialization, the called functionwill be empty or return without doing anything.

Functions Called

ESAL_TS_MEM_BSS_Clear

ESAL_TS_MEM_ROM_To_RAM_Copy

ESAL_TS_RTE_Initialize

ESAL ComponentESAL_GE_STK_Except_Stack_Init


ESAL_GE_STK_Except_Stack_InitUsage

static VOID ESAL_GE_STK_Except_Stack_Init(VOID)

Description

This function initializes the exception handling stack. It sets the initial value of the globalexception stack pointer variable (ESAL_GE_STK_Exception_SP) and aligns it as required forthe toolset.


ESAL ComponentESAL_GE_STK_Initialize

December 15, 2006

ESAL_GE_STK_InitializeUsage

VOID ESAL_GE_STK_Initialize (VOID (*unsol_stk_switch_entry)(VOID))

Description

This function initializes the system stack and the exception handling stack. It sets the initialvalue of the global stack pointer variable (ESAL_GE_STK_System_SP) and aligns it asrequired for the toolset. It calls ESAL_GE_STK_Except_Stack_Init initialize the exceptionhandling stack. The argument is set as the entry point (ESAL_GE_STK_Unsol_Switch_OS_Entry) into the operating system for an unsolicited stack switch.

Functions Called

ESAL_GE_STK_System_SP_End_Get

ESAL_GE_STK_ALIGN

ESAL_GE_STK_Except_Stack_Init

ESAL ComponentESAL_GE_STK_System_SP_End_Get


ESAL_GE_STK_System_SP_End_GetUsage

VOID *ESAL_GE_STK_System_SP_End_Get (VOID)

Description

This function returns the ending address of the system stack (ESAL_GE_STK_System_SP_Memory).


ESAL ComponentESAL_GE_STK_System_SP_Start_Get

December 15, 2006

ESAL_GE_STK_System_SP_Start_GetUsage

VOID *ESAL_GE_STK_System_SP_Start_Get (VOID)

Description

This function returns the starting address of the system stack (ESAL_GE_STK_System_SP_Memory).

ESAL ComponentESAL_GE_STK_Unsol_Switch_Default


ESAL_GE_STK_Unsol_Switch_DefaultUsage

static VOID ESAL_GE_STK_Unsol_Switch_Default (VOID)

Description

This function is the default unsolicited stack switch entry. It is used when the ESAL_GE_STK_Initialize function is called with a null unsol_stk_switch_entry argument.


ESAL ComponentESAL_GE_TMR_OS_ISR_Register

December 15, 2006

ESAL_GE_TMR_OS_ISR_RegisterUsage

VOID ESAL_GE_TMR_OS_ISR_Register (VOID (*isr_func_ptr)(INT))

Description

This function registers the OS’s timer interrupt service routine.

Functions Called


ESAL ComponentESAL_GE_TMR_OS_Timer_Start


ESAL_GE_TMR_OS_Timer_StartUsage

VOID ESAL_GE_TMR_OS_Timer_Start (UINT32 ticks_per_sec)

Description

This function initializes and starts the OS timer by calling the appropriate component timer startfunctions with the ticks_per_sec parameter. The component configuration setting ESAL_AR_OS_TIMER_USED determines which one, or more, of the respective OS timer start functionsare executed. Some ports require timer initialization at more than one component level.

Functions Called

ESAL_PR_TMR_OS_Timer_Start

[ESAL_AR_TMR_OS_Timer_Start]


ESAL ComponentToolset Specific Component (TS)

December 15, 2006

Toolset Specific Component (TS)The ESAL toolset component (TS) is responsible for performing any operations specific to thegiven toolset. Typically, TS functions relate to run-time environment support, memory, andstack operations.

Toolset Specific Component FilesThe ESAL toolset component consists of the files defined in the following table.

* Due to architectural and performance requirements, some of the functions in this file arenormally written in the processor’s native assembly language. Therefore, there may anassembly language file in addition to (or as a replacement for) this C file. In addition, anynecessary constants will be found in a corresponding assembly language include file (*.inc).

Table 5-7.

File Description

esal_ts_cfg.h This file contains required configurationsettings for the given toolset. Othercomponents may refer to these settings

esal_ts_rte_defs.h This file contains toolset specific structures,data types, etc., related to run-timeenvironment requirements

esal_ts_stk_defs.h This file contains toolset specific definitions,structures, macros, etc., related to stacks.esal_ts_mem.c

esal_ts_mem.c This file contains toolset specific functionsrelated to memory

esal_ts_rte.c *(esal_ts_rte_a.<s>)

This file contains toolset functions related torun-time environment requirements

esal_ts_stk.c *(esal_ts_stk_a.<s>)

This file contains toolset functions related tostacks (includes context switching functions)

ESAL ComponentToolset Specific Component (TS)


Toolset Specific Component Data Structures

Toolset Stack FrameESAL saves and restores a toolset stack frame for a given execution thread as a result of asolicited thread switch or when setting up the thread’s entry point. The ESAL_TS_STK datastructure is specific to the toolset. It will always contain the stack type (set to ESAL_GE_STK_TS_TYPE) and a return address (or entry point) used when resuming (or starting) execution ofthe thread.

Field Declarations

UINT32 stack_type;UINT32 <other stack items>;UINT32 rtn_address;

Field Summary

Toolset Specific Component FunctionsThe following sections provide a brief description of the functions in the TS component.Review of the actual source code is recommended for further information.

Table 5-8.

Field Description

stack_type This is the type of stack (always set toESAL_GE_STK_TS_ TYPE)

<other stack items> One or more toolset specific stack items

rtn_address Point to resume (or start) execution of the thread


ESAL ComponentESAL_TS_MEM_BSS_Clear

December 15, 2006

ESAL_TS_MEM_BSS_ClearUsage

VOID *ESAL_TS_MEM_BSS_Clear (VOID)

Description

This function clears the BSS area, specified by the given toolset. This is a toolset specificfunction. Typically the BSS start address and length are obtained from linker producedaddresses and labels. If the toolset does not provide the BSS starting address and length (theparameters required for the ESAL_GE_MEM_Clear call) the parameters may be defined in alinker control file, a system header file, or any convenient location. Once the requiredparameters are obtained the ESAL generic memory clear function or an equivalent toolsetfunction may be called.

ESAL ComponentESAL_TS_MEM_First_Avail_Get


ESAL_TS_MEM_First_Avail_GetUsage

VOID *ESAL_TS_MEM_First_Avail_Get (VOID)

Description

This function returns a pointer to the first memory address available for use. This is a toolsetspecific function. Typically this value is obtained from linker produced addresses and labels andis a static value (i.e. it will not be updated at run-time to reflect use of the available memory).The value only represents the first available memory address that existed at link time.

NoteIf the toolset does not automatically generate a suitable linker produced label, a labelmust be added to the linker command file, a system header file, or some other convenientmethod should be used to define the label.


ESAL ComponentESAL_TS_MEM_ROM_To_RAM_Copy

December 15, 2006

ESAL_TS_MEM_ROM_To_RAM_CopyUsage

VOID *ESAL_TS_MEM_ROM_To_RAM_Copy (VOID)

Description

This function copies initialized data from ROM to RAM. This places initialized data items intoRAM to allow them to be modified dynamically. This is a toolset specific function. Frequently,the toolset provides this as a toolset library function, but, if not, it is up to the developer toimplement this function. Usually the toolset linker will provide addresses and (or) symbols thatidentify where in the program image the initialized data is located and the size of the data.Likewise, the start of the RAM data area is also identified. The toolset provided data must beconverted into the parameters required for the copy function that is used.

NoteESAL always calls this function during initialization. Therefore, this function must beprovided even if the executable is not being built to execute from ROM. When notexecuting from ROM, the function returns without doing anything.

ESAL ComponentESAL_TS_RTE_Initialize


ESAL_TS_RTE_InitializeUsage

VOID ESAL_TS_RTE_Initialize (VOID)

Description

This function initializes the run-time environment as required for the given toolset. This is atoolset specific function. When called, the low level (assembly) and C level initialization of thebasic run-time memory environment has already been performed. This functions performs anyrun-time environment initialization in addition to this. For many toolsets this function will beempty.

The toolset’s run-time requirements are usually found in the toolset compiler manual.


ESAL ComponentESAL_TS_RTE_Lowlevel_Initialize

December 15, 2006

ESAL_TS_RTE_Lowlevel_InitializeUsage

VOID ESAL_TS_RTE_Lowlevel_Initialize (VOID)

Description

This function is normally executed from assembly language prior to ESAL_TS_RTE_Initialize.It performs run-time environment initialization that can only be performed from assemblylanguage. This is a toolset specific function that sets up any required components (registers,processor modes, etc.) to ensure correct execution of the C language environment. Uponcompletion of RTE setup, the OS specific initialization entry point is called ( OS_Init_Entry).See the ESAL initialization flow chart at the end of this chapter.

The toolset’s run-time requirements are usually found in the toolset compiler manual. Due toarchitectural requirements and because this function is called during assembly levelinitialization, this function is written as an assembly function contained in esal_ts_rte_a.<s>.

Functions Called

Operating System Initialization Entry Point (OS_Init_Entry)

ESAL ComponentESAL_TS_STK_Solicited_Restore


ESAL_TS_STK_Solicited_RestoreUsage

VOID *ESAL_TS_STK_Solicited_Restore (VOID *stack_ptr)

Description

This function restores registers from a solicited stack frame pointed to by *stack_ptr andreturns control to the point specified in the restored frame. This is a toolset specific function thatis responsible for restoring the registers from the stack that are part of a toolset (solicited) stackframe (defined in esal_ts_stk_defs.s). After the stack frame has been restored, the appropriate“return to caller” instruction for the given architecture is executed using the rtn_addresscontained in the restored stack frame.

Due to architectural requirements and performance requirements this function is normallywritten as an assembly function contained in an esal_ts_rte_a.<s>.


ESAL ComponentESAL_TS_STK_Solicited_Set

December 15, 2006

ESAL_TS_STK_Solicited_SetUsage

VOID *ESAL_TS_STK_Solicited_Set (VOID *start_addr, VOID *end_addr, VOID(*entry_function) (VOID))

Description

This is a toolset specific function that is responsible for creating an execution thread’s initialtoolset (solicited) stack. This function uses generic stack defines, from esal_ge_stk_defs.h,along with defines in esal_ts_stk_defs.h, to calculate the location of the initial solicited stackframe within the total address space allocated to the stack. A void pointer to the start of the stackframe is returned.

ESAL ComponentESAL_TS_STK_Solicited_Switch


ESAL_TS_STK_Solicited_SwitchUsage

VOID ESAL_TS_STK_Solicited_Switch (VOID *call_back_param, VOID (*call_back)(VOID), VOID **stack_ptr)

Description

This function saves the necessary registers, designated by a given toolset, which must bepreserved across a function call boundary, to the current stack. This is referred to as a solicitedstack. The format of this stack frame is contained in esal_ts_stk_defs.h. The last item pushed onthe stack is the stack type (ESAL_GE_STL_TS_TYPE). The resultant stack pointer (after thetoolset registers and stack type have been saved) is saved to the location specified in the thirdinput parameter (**stack_ptr). Control is then transferred to the specified callback function.

NoteThe call_back_param variable is placed into the appropriate parameter register or on thestack before calling the call_back function. This allows call_back functions that require asingle parameter to utilize this value. Additionally, the call_back_param was purposelyselected as the first parameter to this function to allow it to easily be passed as the firstparameter to the call_back function without moving it. This applies only to architecturesthat use register-based parameter passing.


ESAL ComponentArchitecture Specific Component (AR)

December 15, 2006

Architecture Specific Component (AR)The ESAL architecture specific component (AR) is responsible for performing any operationsspecific to the target architecture. Typically, AR functions relate to interrupt control, interruptservicing, stacks and timer operations.

Architecture Specific Component FilesThe ESAL architecture component consists of the files defined in the following table.

Table 5-9.

File Description

esal_ar_cfg.h This file contains required configuration settingsfor the target architecture. Other components mayrefer to these settings.

esal_ar_dbg_defs.h This file contains the architecture specificdefines, structures, data types, and so on, relatedto debugging.

esal_ar_int_defs.h This file contains architecture specificdefinitions, structures, assembly macros, and soon, related to interrupt control.

esal_ar_isr_defs.h This file contains architecture specificdefinitions, structures, assembly macros, and soon, related to interrupt servicing.

esal_ar_stk_defs.h This file contains the architecture specificdefinitions, structures, macros, and so on, relatedto stacks.

esal_ar_tmr_defs.h This file contains architecturally specificdefinitions, structures, assembly macros, and soon, related to timers.

esal_ar_isr.c *(esal_ar_isr_a.<s>)

This file contains architecturally specificfunctions related to interrupt servicing.

esal_ar_stk.c *(esal_ar_stk_a.<s>)

This file contains architecturally specificfunctions related to stacks.

esal_ar_tmr.c This file contains architecturally specificfunctions related to timers.

esal_ar_dbg.c This file contains the architecture specificfunctions related to debugging.



* Due to architectural and performance requirements, some of the functions in this file arenormally written in the processor’s native assembly language. Therefore, there may be anassembly language file in addition to (or as a replacement for) this C file. In addition, anynecessary constants will be found in a corresponding assembly language include file (*.inc).

Architecture Specific Data Structures

Architecture Interrupt Control VariablesESAL macros ESAL_AR_INT_ALL_DISABLE and ESAL_AT_INT_ALL_RESTORE.requires architecture specific variables in order to save and restore the architecture interruptstate The macro ESAL_AR_INT_CONTROL_VARS is defined to declare these variables.

Architecture Vector TableThe ESAL_AR_ISR_Vector_Table identifies the start address of the vector table or exceptionhandling code used by the target architecture. The actual implementation of this table will varygreatly across different architectures. For example it may be an array of function pointers or anarray of assembly instructions.

Minimum Architecture Stack FrameESAL saves and restores a minimum architecture stack frame for a given execution thread as aresult of an unsolicited context switch.. The ESAL_AR_STK_MIN data structure is specific tothe architecture and contains the minimum architecture registers required to be saved in order toenter a C environment during an interrupt or exception. These registers are the “scratch”registers that will not be preserved across a function call boundary, and any interrupt stateregisters that must preserved to allow interrupt nesting. This will always include a returnaddress used when resuming execution of the thread.

Field Declarations

UINT32 <other stack items>;UINT32 rtn_address;

esal_ar_dbg_a.s This file contains the architecture specificfunctions and data related to debugging assemblylanguage service routines.

Table 5-9. (cont.)

File Description



December 15, 2006

Field Summary

Architecture Stack FrameESAL may save and restore a complete architecture stack frame, for a given execution thread asa result of an unsolicited context switch. The ESAL_AR_STK data structure is specific to thearchitecture and contains the minimum architecture stack frame and any other items that mustbe preserved across an unsolicited (interrupt) context switch. It will always contain a stack type.

Field Declarations

UINT32 stack_type;UINT32 <other stack items>;ESAL_AR_STK_MIN min_stack;

Field Summary

Architecture Specific Component FunctionsThe following sections provide a brief description of the functions in the AR component.Review of the actual source code is recommended for further information.

Table 5-10.

Field Description

<other stack items> One or more architecture specific stack items

rtn_address Point to resume (or start) execution of the thread

Table 5-11.

Field Description

stack_type This is the type of stack (always set toESAL_GE_STK_AR_TYPE)

<other stack items> One or more architecture specific stack items

min_stack The minimum stack frame, including the rtn_address

ESAL ComponentESAL_AR_DBG_Initialize


ESAL_AR_DBG_InitializeUsage

VOID ESAL_AR_DBG_Initialize(VOID)

Description

This function initializes debugging at the architecture level.


• Creates a Register Offset Table for the architecture specific registers that are saved onthe stack

• Retrieves and saves the architecture specific exception vector that will be replaced withthe Debug Break Exception Handler

• Installs the ESAL_AR_DBG_BRK_Handler in the Exception Vector Table (EVT).

Functions Called

ESAL_GE_EXCEPT_HANDLER_GET

ESAL_GE_EXCEPT_HANDLER_SET


ESAL ComponentESAL_AR_DBG_Reg_Read

December 15, 2006

ESAL_AR_DBG_Reg_ReadUsage

INT ESAL_AR_DBG_Reg_Read(VOID *stack_pointer, INT reg_no, ESAL_GE_DBG_REG*reg_val)

Description

This function reads the value of a specified register on the stack.


• Performs legality tests on the input parameters

• Retrieves the specified stack register and stores it at the specified location.

Functions Called

ESAL_GE_STK_TYPE_GET

ESAL_GE_MEM_READ32

ESAL ComponentESAL_AR_DBG_Reg_Write


ESAL_AR_DBG_Reg_WriteUsage

INT ESAL_AR_DBG_Reg_Write(VOID *stack_pointer, INT reg_no,ESAL_GE_DBG_REG *reg_val)

Description

This function writes a value to a specified register on the stack.


• Performs legality tests on the input parameters

• Stores the passed value at the correct offset on the stack.

Functions Called

ESAL_GE_STK_TYPE_GET

ESAL_GE_MEM_WRITE32


ESAL ComponentESAL_AR_DBG_Opcode_Read

December 15, 2006

ESAL_AR_DBG_Opcode_ReadUsage

ESAL_GE_DBG_OPCODE ESAL_AR_DBG_Opcode_Read(VOID *read_addr)

Description

This function reads a 4 byte (or 2 byte for Thumb Mode) instruction from the specified address.


• Tests if executing in Normal or Thumb mode

• Calls the appropriate read routine to obtain the opcode to return.

Functions Called

[ESAL_GE_MEM_READ32]


ESAL ComponentESAL_AR_DBG_Opcode_Write


ESAL_AR_DBG_Opcode_WriteUsage

VOID ESAL_AR_DBG_Opcode_Write(VOID *write_addr, ESAL_GE_DBG_OPCODEopcode)

Description

This function writes a 4 byte (or 2 byte for Thumb Mode) instruction to the specified address.



• Calls the appropriate routines to write the passed opcode to the specified address

• Invalidate both Data and Instruction caches for the address written to.

Functions Called

[ESAL_GE_MEM_32BIT_CLEAR]

[ESAL_GE_MEM_WRITE16]

[ESAL_GE_MEM_WRITE32]

[ESAL_GE_MEM_DCACHE_FLUSH_INVAL]

[ESAL_GE_MEM_ICACHE_INVALIDATE]


ESAL ComponentESAL_AR_DBG_Opcode_Brk_Get

December 15, 2006

ESAL_AR_DBG_Opcode_Brk_GetUsage

ESAL_GE_DBG_OPCODE ESAL_AR_DBG_Opcode_Brk_Get(VOID *addr)

Description

This function returns the correct breakpoint opcode depending on the mode (Thumb orNormal).



• Returns the Normal or Thumb mode Breakpoint opcode.

Functions Called

None.

ESAL ComponentESAL_AR_DBG_Step_Addr_Get


ESAL_AR_DBG_Step_Addr_GetUsage

VOID ESAL_AR_DBG_Step_Addr_Get(VOID *addr, VOID *stack_frame)

Description

This function returns next program counter (next instruction to be executed) from the specifiedinstruction.

The logic required to correctly determine the address of the next instruction to be executed iscomplex and requires a comprehensive understanding of the target processor’s instruction set.For a detailed explanation of this function refer to the source code contained in the esal_ar_dbg.c file.

This function performs the steps required to evaluate the instruction at the passed address todetermine the address of the next instruction to be executed.

Functions Called

ESAL_GE_MEM_READ32

ESAL_AR_DBG_Reg_Read

ESAL_AR_DBG_Condition_Met

[ESAL_GE_MEM_32BIT_VAL_GET]

[ESAL_GE_MEM_32BIT_TEST]

[ESAL_GE_MEM_32BIT_CLEAR]


ESAL ComponentESAL_AR_DBG_Condition_Met

December 15, 2006

ESAL_AR_DBG_Condition_MetUsage

static INT ESAL_AR_DBG_Condition_Met(UINT cpsr, UINT inst, INT thumb)

Description

This function tests if a conditional instruction’s condition is met.

The logic required to correctly determine if a conditional instruction’s condition is met iscomplex and requires a comprehensive understanding of the target processor’s instruction set.For a detailed explanation of this function refer to the source code contained in theesal_ar_dbg.c file.

This function performs the steps required to evaluate the passed instruction’s conditional basedupon the current processor state. The result of the evaluation is returned to the calling function.

Functions Called

ESAL_GE_MEM_32BIT_MASK_TEST

ESAL ComponentESAL_AR_DBG_Reg_Shifted_Get


ESAL_AR_DBG_Reg_Shifted_GetUsage

static UINT ESAL_AR_DBG_Reg_Shifted_Get(UINT inst, INT carry, UINT prog_counter,UINT cpsr, VOID *stack_frame))

Description

The logic required to correctly evaluate a shift instruction is complex and requires acomprehensive understanding of the target processor’s instruction set. For a detailedexplanation of this function refer to the source code contained in the esal_ar_dbg.c file.

This function evaluates a shift instruction and returns a result equal to what would be producedif the specified instruction was executed.

Functions Called

ESAL_GE_MEM_32BIT_VAL_GET

ESAL_GE_MEM_32BIT_TEST

[ESAL_AR_DBG_Reg_Read]


ESAL ComponentESAL_AR_DBG_Brk_Handler

December 15, 2006

ESAL_AR_DBG_Brk_HandlerUsage

static VOID ESAL_AR_DBG_Brk_Handler(INT exception_vector, VOID *stack_ptr)

Description

This function is the breakpoint handler for the architecture.

This function performs the following processing:

• Test if executing in Regular (ARM) mode or Thumb mode

• Read the exception opcode from the stack frame

• Set the brk_exception flag to indicate the execution mode (ARM or Thumb)

• If the opcode read from the stack is not a Break exception call the application’s normalexception handler

• If the opcode read from the stack frame is a Break exception (ARM or Thumb) updatethe global debug variables with the return address and SPSR register values from thestack. Change the return address on the stack to return through the assembly languageESAL_AR_DBG_Brk_Exit (contained in the esal_ar_dbg_a.s file).

Functions Called

ESAL_GE_MEM_32BIT_MASK_TEST



[ESAL_AR_DBG_Orig_Brk_Handler]

ESAL ComponentESAL_AR_DBG_Brk_Exit


ESAL_AR_DBG_Brk_ExitUsage

ESAL_AR_DBG_Brk_Exit

Description

This assembly language routine provides the exit from a Debug Break exception for thearchitecture.

This function saves the minimal context on the stack and calls the unsolicited context switchfunction.

Functions Called

ESAL_AR_DBG_OS_Brk_Handler

ESAL_AR_STK_Unsolicited_Switch


ESAL ComponentESAL_AR_INT_Enable

December 15, 2006

ESAL_AR_INT_EnableUsage

VOID ESAL_AR_INT_Enable (INT vector_id, ESAL_GE_INT_TRIG_TYPE trigger_type,INT priority)

Description

This function enables the given interrupt source with the specified attributes (if applicable to thegiven architecture).

This function is included based on the vector IDs defined in esal_ar_int_defs.h. If noarchitecture interrupt vector IDs are defined, this function is not included.

Functions Called

Architecture specific

ESAL ComponentESAL_AR_INT_Disable


ESAL_AR_INT_DisableUsage

VOID ESAL_AR_INT_Disable (INT vector_id)

Description

This function disables the given interrupt source

This function is included based on the vector IDs defined in esal_ar_int_defs.h. If noarchitecture interrupt vector IDs are defined, this function is not included.

Functions Called

[ESAL_AR_INT_Disable]

[ESAL_DP_INT_Disable]

[ESAL_PR_INT_Disable]


ESAL ComponentESAL_AR_ISR_<Exception_Type>_Handler

December 15, 2006

ESAL_AR_ISR_<Exception_Type>_HandlerUsage

static VOID ESAL_AR_ISR_<Exception_Type>_Handler (VOID)

Description

This function performs the minimum number of steps required to enable calling theexceptions’s C language handler. In general this function will:

• Save minimal registers (required to enter a C language environment) to the stack of theinterrupted execution thread.

NoteThe registers saved must match the ESAL_AR_STK_MIN structure defined inesal_ar_stk_defs.h.

• Determine and put the exeception vector ID into the first C parameter register

• Put the hardware stack pointer (resultant stack pointer after step 1) in the second Cparameter register

• Execute the architecture exception handler for the given exception

• Restore the minimal registers saved in step 1

• Return to the point of the exception

Due to architectural and performance requirements, this function is normally written as anassembly language function.

Functions Called

Architecture Specific

ESAL ComponentESAL_AR_ISR_<Interrupt_Type>_Handler


ESAL_AR_ISR_<Interrupt_Type>_HandlerUsage

static VOID ESAL_AR_ISR_<Interrupt_Type>_Handler (VOID)

Description

This function performs the minimum number of steps required to enable calling the OS’s Clanguage interrupt handlers. See the ESAL low-level interrupt sequence flow chart at the end ofthis chapter. In general this function will:

• If ESAL_AR_ISR_HOOK_ENABLED is TRUE

o Save minimal registers required for calling an assembly function

o ESAL_AR_ISR_HOOK is called, allowing an application specific function toexecute whenever an interrupt is detected

o Restore the previously saved registers

• Save minimal registers (required for calling a C function) to the stack of the interruptedexecution thread.

NoteThe registers saved must match the ESAL_AR_STK_MIN structure defined inesal_ar_stk_defs.h.

• Determine and put the interrupt vector ID into the first C parameter register

• Put the hardware stack pointer (resultant stack pointer after step 1) in the second Cparameter register

• Determine if an interrupt service routine is already executing

• If an interrupt is already executing

o Call ESAL_GE_ISR_OS_Nested_Entry, the OS’s nested interrupt handler

• If an interrupt is not already executing

o Switch to the system stack

o Call ESAL_GE_ISR_OS_Entry, the OS’s non-nested interrupt handler

o Determine if the interrupt caused an unsolicited stack switch

o If an unsolicted stack switch is needed

• Call ESAL_AR_STK_Unsolicited_Switch, ESAL’s unsolicited stack switchfunction, which does not return here

• Restore the registers previously saved in step 2


ESAL ComponentESAL_AR_ISR_<Interrupt_Type>_Handler

December 15, 2006

• Return to the point of the interrupt


Functions Called

[ESAL_AR_ISR_HOOK]

ESAL_GE_ISR_OS_Nested_Entry

ESAL_GE_ISR_OS_Entry

ESAL_AR_STK_Unsolicited_Switch

ESAL ComponentESAL_AR_ISR_Initialize


ESAL_AR_ISR_InitializeUsage

VOID ESAL_AR_ISR_Initialize (VOID)

Description

This function performs any interrupt service routine related initialization necessary for the givenarchitecture. This includes setting up interrupt related stacks, initializing data used duringinterrupt handling, etc.

This function is included in the ESAL library only if the conditional below, contained inesal_ar_cfg.h, is defined as ESAL_TRUE.

ESAL_AR_ISR_INIT_REQUIRED


Functions Called

Architecture Specific


ESAL ComponentESAL_AR_ISR_Return

December 15, 2006

ESAL_AR_ISR_ReturnUsage

VOID ESAL_AR_ISR_Return (VOID (*rtn_func_ptr)(VOID))

Description

This function performs a “return from interrupt” or similar architecture specific instruction toreturn to the requested function after servicing an interrupt. See the macro ESAL_GE_ISR_OS_RETURN.

This function is included in the ESAL library only if the conditional below, contained inesal_ar_cfg.h, is defined as ESAL_TRUE.

ESAL_AR_ISR_RTI_MANDATORY

Due to architectural and performance requirements, this function is normally written as anassembly function contained in esal_ar_isr_a.<s>.

ESAL ComponentESAL_AR_ISR_Vector_Table_Install


ESAL_AR_ISR_Vector_Table_InstallUsage

VOID ESAL_AR_ISR_Vector_Table_Install (VOID)

Description

This function installs the vector table as required for the architecture. This may include copyingvectors from ROM to RAM, or setting the appropriate control register to point to the vectortable that is to be used. In general the following steps are accomplished by this function:

Test if the vector table is already installed at required location

If vector table not installed as required, perform the necessary operations to install the vectortable to the required location for the given architecture.


ESAL ComponentESAL_AR_STK_SP_GET

December 15, 2006

ESAL_AR_STK_SP_GETUsage

VOID * ESAL_AR_STK_SP_GET (VOID)

Description

This macro returns the contents of the Stack-Pointer register for the given architecture.

Due to architectural and performance requirements, this function is normally written as an in-line assembly macro contained in esal_ar_stk_defs.h.

ESAL ComponentESAL_AR_STK_SP_SET


ESAL_AR_STK_SP_SETUsage

VOID ESAL_AR_STK_SP_SET (VOID *stack_pointer)

Description

This macro sets the Stack-Pointer register for the given architecture to the passed in address.

Due to architectural and performance requirements, this function is normally written as an in-line assembly macro contained in esal_ar_stk_defs.h.


ESAL ComponentESAL_AR_STK_Startup_SP_Set

December 15, 2006

ESAL_AR_STK_Startup_SP_SetUsage

VOID ESAL_AR_STK_Startup_SP_Set (VOID)

Description

This function sets the architecture stack pointer to an address that can be used duringinitialization. This can include on-chip SRAM, available RAM not used by the applicationduring initialization, etc. This is a temporary stack pointer. The OS switches to the system stackpointer by calling ESAL_GE_STK_Initialize.

Due to architectural requirements and because this function is called during assembly levelinitialization, this function is written as an assembly function contained in esal_ar_stk_a.<s>.

Functions Called

ESAL_TS_RTE_Lowlevel_Initialize

ESAL ComponentESAL_AR_STK_Unsolicited_Restore


ESAL_AR_STK_Unsolicited_RestoreUsage

VOID ESAL_AR_STK_Unsolicited_Restore (VOID *stack_ptr)

Description

This function restores registers from an architecture (unsolicited / interrupt) stack frame pointedto by *stack_ptr parameter and returns control to the point specified in the restored frame. Thisfunction is responsible for restoring the registers from the stack that are part of an architecture(unsolicited, or interrupt) stack frame (defined in esal_ar_stk_defs.h). After the stack frame hasbeen restored the appropriate “return from interrupt” instruction for the given architecture isexecuted using the rtn_address contained in the restored stack frame.

Due to architectural and performance requirements, this function is normally written as anassembly function contained in esal_ar_stk_a.<s>.


ESAL ComponentESAL_AR_STK_Unsolicited_Set

December 15, 2006

ESAL_AR_STK_Unsolicited_SetUsage

VOID *ESAL_AR_STK_Unsolicited_Set (VOID *start_addr, VOID end_addr, VOID(*entry_function) (VOID))

Description

This function populates an architecture (unsolicited / interrupt) stack frame as required by thegiven architecture. This function uses generic stack defines, from esal_ge_stk_defs.h, alongwith data in esal_ar_stk_defs.h, to calculate the location of the initial unsolicited stack framewithin the total address space allocated to the stack.

ESAL ComponentESAL_AR_TMR_OS_Timer_Start


ESAL_AR_TMR_OS_Timer_StartUsage

VOID ESAL_AR_TMR_OS_Timer_Start UINT32 ticks_per_sec)

Description

This function starts the Operating System timer at the architecture level. This may includedetermining the required timer count for the specified period, enabling the timer to produce thisperiod, and enabling the interrupt associated with this timer. The generic macro ESAL_GE_TMR_COUNT_CALC is called to calculate the timer count value for a timer with a given clockrate, clock prescale and period.

The function in this file is included only if the conditional below, contained in esal_ar_stk_defs.h, is defined as ESAL_TRUE.

ESAL_AR_OS_TIMER_USED

Functions Called

ESAL_GE_TMR_COUNT_CALC


ESAL ComponentCore Specific Component (CO)

December 15, 2006

Core Specific Component (CO)The ESAL core component (CO) is responsible for performing any operations specific to thetarget core. Typically, CO functions relate to memory operations.

Core Specific Component FilesThe ESAL core specific component consists of the files defined in the following table.

Core Specific Component FunctionsThe following sections provide a brief description of the functions in the CO component.Review of the actual source code is recommended for further information.

Table 5-12.

File Description

esal_co_cfg.h This file contains required configuration settings for thetarget core. Other components may refer to these settings

esal_co_mem_defs.h This file contains architecture specific definitions,structures, assembly macros, etc., related to memory

esal_co_mem.c This file contains core specific functions related tomemory

ESAL ComponentESAL_CO_MEM_Cache_Enable


ESAL_CO_MEM_Cache_EnableUsage

VOID *ESAL_CO_MEM_Cache_Enable (VOID *avail_mem)

Description

This function initializes the cache as required for the given core. The memory region datastructure ESAL_DP_MEM_Region_Data(defined in esal_dp_mem.c) is utilized to perform thisinitialization and the cache attributes in that table are used when the cache parameters are set.The ESAL_DP_MEM_Region_Data structure contains information about all usable memoryregions on the target. Also, it is worth noting that it is often necessary to perform some corespecific initialization, such as initializing an MMU, prior to actually enabling the cache.

This function is included only if the conditional below, contained in esal_co_cfg.h, is defined asESAL_TRUE.

ESAL_ESAL_CO_CACHE_AVAILABLE


ESAL ComponentESAL_CO_MEM_CACHE_ALL_INVALIDATE

December 15, 2006

ESAL_CO_MEM_CACHE_ALL_INVALIDATEUsage

VOID ESAL_CO_MEM_CACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all cache (instruction and data) at the core level (level 1 cache).



ESAL ComponentESAL_CO_MEM_ICACHE_ALL_INVALIDATE


ESAL_CO_MEM_ICACHE_ALL_INVALIDATEUsage

VOID ESAL_CO_MEM_ICACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all instruction cache at the core level (level 1 cache).




ESAL ComponentESAL_CO_MEM_DCACHE_ALL_INVALIDATE

December 15, 2006

ESAL_CO_MEM_DCACHE_ALL_INVALIDATEUsage

VOID ESAL_CO_MEM_DCACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all data cache at the core level (level 1 cache).



ESAL ComponentESAL_CO_MEM_ICACHE_INVALIDATE


ESAL_CO_MEM_ICACHE_INVALIDATEUsage

VOID ESAL_CO_MEM_ICACHE_INVALIDATE (VOID *addr, UINT32 size)

Description

This macro invalidates the instruction cache for the specified address range at the core level(level 1 cache).



This function may not be possible to implement based on the cache functionality provided bythe core. If functionality is not available, this function will cause ALL instruction cache to beinvalidated.


ESAL ComponentESAL_CO_MEM_DCACHE_INVALIDATE

December 15, 2006

ESAL_CO_MEM_DCACHE_INVALIDATEUsage

VOID ESAL_CO_MEM_DCACHE_INVALIDATE (VOID *addr, UINT32 size)

Description

This macro invalidates the data cache for the specified address range at the core level (level 1cache).



This function may not be possible to implement based on the cache functionality provided bythe core. If functionality is not available, this function will cause ALL data cache to beinvalidated.

ESAL ComponentESAL_CO_MEM_DCACHE_ALL_FLUSH_INVAL


ESAL_CO_MEM_DCACHE_ALL_FLUSH_INVALUsage

VOID ESAL_CO_MEM_DCACHE_ALL_FLUSH_INVAL (VOID)

Description

This macro causes all the data cache to be written to physical memory and then invalidated atthe core level (level 1 cache).



This function only applies to writeback / copyback cache regions. If writeback/copyback cacheis not available for a specific core, this macro will do nothing.


ESAL ComponentESAL_CO_MEM_DCACHE_FLUSH_INVAL

December 15, 2006

ESAL_CO_MEM_DCACHE_FLUSH_INVALUsage

VOID ESAL_CO_MEM_DCACHE_FLUSH_INVAL (VOID *addr, UINT32 size)

Description

This macro causes the data cache for the specified address range to be written to physicalmemory and then invalidated at the core level (level 1 cache).



This function only applies to writeback / copyback cache regions. If writeback/copyback cacheis not available for a specific core, this macro will do nothing.

This function may not be possible to implement based on the cache functionality provided bythe core. If functionality is not available, this function will cause ALL data cache to be writtento physical memory and invalidated.

ESAL ComponentProcessor Specific Component (PR)


Processor Specific Component (PR)The ESAL processor component (PR) is responsible for performing any operations specific tothe target processor. Typically, PR functions relate to interrupt control, interrupt servicing,memory and timer operations.

Processor Specific Component FilesThe ESAL processor specific component consists of the files defined in the following table.

Processor Specific Component FunctionsThe following sections provide a brief description of the functions in the PR component.Review of the actual source code is recommended for further information.

Table 5-13.

File Description

esal_pr_cfg.h This file contains required configuration settings for thetarget processor. Other components may refer to thesesettings

esal_pr_int_defs.h This file contains processor specific definitions, structures,assembly macros, etc., related to interrupt control

esal_pr_isr_defs.h This file contains processor specific definitions, structures,assembly macros, etc., related to interrupt servicing.

esal_pr_mem_defs.h This file contains processor specific definitions, structures,assembly macros, etc., related to memory

esal_pr_tmr_defs.h This file contains processor specific definitions, structures,assembly macros, etc., related to timers.

esal_pr_int.c This file contains processor specific functions related tointerrupt control

esal_pr_isr.c This file contains processor specific functions related tointerrupt servicing

esal_pr_mem.c This file contains processor specific functions related tomemory

esal_pr_tmr.c This file contains processor specific functions related totimers


ESAL ComponentESAL_PR_INT_All_Disable

December 15, 2006

ESAL_PR_INT_All_DisableUsage

VOID ESAL_PR_INT_All_Disable (VOID)

Description

This function disables all interrupt sources for the given processor. It sets the values forprocessor interrupt controller registers (mask registers, priority register, pending registers, etc.)to disable all interrupt sources.

This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.

ESAL_PR_INTERRUPTS_AVAILABLE

ESAL ComponentESAL_PR_INT_Enable


ESAL_PR_INT_EnableVOID ESAL_PR_INT_Enable (INT vector_id, ESAL_GE_INT_TRIG_TYPE trigger_type,

INT priority)

Description

This function enables the given interrupt source with the specified attributes (if applicable to thegiven processor).



Functions Called

Processor specific


ESAL ComponentESAL_PR_INT_Disable

December 15, 2006

ESAL_PR_INT_DisableUsage

VOID ESAL_AR_INT_Disable (INT vector_id)

Description




ESAL ComponentESAL_PR_ISR_<Interrupt_Type>_Handler


ESAL_PR_ISR_<Interrupt_Type>_HandlerUsage

static VOID ESAL_PR_ISR_Initialize (INT vector)

Description

This function is responsible for handling certain processor level interrupts that were registeredduring initialization. This function performs the minimum number of steps required to enablecalling the specific processor interrupt service routine. In general, this function will:

Determine the interrupt vector ID

Perform necessary procedures to allow nesting of interrupts

Re-enable only the interrupts required to allow interrupt nesting

Execute the ISR for this interrupt by invoking ESAL_GE_ISR_HANDLER_EXECUTE.

Perform necessary procedures to allow recovery from nesting of interrupts



Functions Called

ESAL_GE_ISR_HANDLER_EXECUTE


ESAL ComponentESAL_PR_ISR_Initialize

December 15, 2006

ESAL_PR_ISR_InitializeUsage

VOID ESAL_PR_ISR_Initialize (VOID)

Description

This function is the processor ISR initialization function. It is responsible for registering ISRsfor processor related interrupts. This function also initializes the processor as necessary tosupport interrupt servicing.



Functions Called


ESAL ComponentESAL_PR_MEM_Cache_Enable


ESAL_PR_MEM_Cache_EnableUsage

VOID *ESAL_PR_MEM_Cache_Enable (VOID *avail_mem)

Description

This function initializes the processor cache as required. The memory region data structureESAL_DP_MEM_Region_Data(defined in esal_dp_mem.c) is utilized to perform thisinitialization and the cache attributes in that table are to be used when the cache parameters areset. The ESAL_DP_MEM_Region_Data structure contains information about all usablememory regions on the target.


ESAL_PR_CACHE_AVAILABLE


ESAL ComponentESAL_PR_MEM_CACHE_ALL_INVALIDATE

December 15, 2006

ESAL_PR_MEM_CACHE_ALL_INVALIDATEUsage

VOID ESAL_PR_MEM_CACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all cache (instruction and data) at the processor level (level 2 cache).


ESAL_ESAL_PR_CACHE_AVAILABLE

ESAL ComponentESAL_PR_MEM_ICACHE_ALL_INVALIDATE


ESAL_PR_MEM_ICACHE_ALL_INVALIDATEUsage

VOID ESAL_PR_MEM_ICACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all instruction cache at the processor level (level 2 cache).




ESAL ComponentESAL_PR_MEM_DCACHE_ALL_INVALIDATE

December 15, 2006

ESAL_PR_MEM_DCACHE_ALL_INVALIDATEUsage

VOID ESAL_PR_MEM_DCACHE_ALL_INVALIDATE (VOID)

Description

This macro invalidates all data cache at the processor level (level 1 cache).



ESAL ComponentESAL_PR_MEM_ICACHE_INVALIDATE


ESAL_PR_MEM_ICACHE_INVALIDATEUsage

VOID ESAL_PR_MEM_ICACHE_INVALIDATE (VOID *addr, UINT32 size)

Description

This macro invalidates the instruction cache for the specified address range at the processorlevel (level 2 cache).



This function may not be possible to implement based on the cache functionality provided bythe processor. If functionality is not available, this function will cause ALL instruction cache tobe invalidated.


ESAL ComponentESAL_PR_MEM_DCACHE_INVALIDATE

December 15, 2006

ESAL_PR_MEM_DCACHE_INVALIDATEUsage

VOID ESAL_PR_MEM_DCACHE_INVALIDATE (VOID *addr, UINT32 size)

Description

This macro invalidates the data cache for the specified address range at the processor level(level 2 cache).



This function may not be possible to implement based on the cache functionality provided bythe processor. If functionality is not available, this function will cause ALL data cache to beinvalidated.

ESAL ComponentESAL_PR_MEM_DCACHE_ALL_FLUSH_INVAL


ESAL_PR_MEM_DCACHE_ALL_FLUSH_INVALUsage

VOID ESAL_PR_MEM_DCACHE_ALL_FLUSH_INVAL (VOID)

Description

This macro causes all the data cache to be written to physical memory and then invalidated atthe processor level (level 2 cache).



This function only applies to writeback / copyback cache regions. If writeback / copybackcache is not available for a specific processor, this macro will do nothing.


ESAL ComponentESAL_PR_MEM_DCACHE_FLUSH_INVAL

December 15, 2006

ESAL_PR_MEM_DCACHE_FLUSH_INVALUsage

VOID ESAL_PR_MEM_DCACHE_FLUSH_INVAL (VOID *addr, UINT32 size)

Description

This macro causes the data cache for the specified address range to be written to physicalmemory and then invalidated at the processor level (level 2 cache).



This function only applies to writeback / copyback cache regions. If writeback / copybackcache is not available for a specific processor, this macro will do nothing.

This function may not be possible to implement based on the cache functionality provided bythe processor. If functionality is not available, this function will cause ALL data cache to bewritten to physical memory and invalidated.

ESAL ComponentESAL_PR_MEM_Initialize


ESAL_PR_MEM_InitializeUsage

VOID ESAL_PR_MEM_Initialize (VOID)

Description

This function initializes the memory interfaced to the target processor. This includes initializingchip-selects, SDRAM controllers, and any other memory related hardware. When the ESAL_PR_ROM_SUPPORT_ENABLED conditional is enabled, code to support execution fromROM is included in this function. The ROM support code should initialize memory controllers,chip-selects, etc., to allow access to volatile memory (RAM) when running from ROM. Accessto this memory must be done before entering a C environment so that stacks can be set up andutilized for function calls. After initializing memory, a jump (or branch) is made to enter theinitialization function ESAL_AR_STK_Startup_SP_Set. Control does not return to thisfunction. See the ESAL initialization flow chart at the end of this chapter.

NoteBecause this function is called during assembly level initialization, this function isusually written in assembly language and is contained in esal_pr_mem_a.<s>.

Functions Called

ESAL_AR_STK_Startup_SP_Set


ESAL ComponentESAL_PR_TMR_OS_Timer_Start

December 15, 2006

ESAL_PR_TMR_OS_Timer_StartUsage

VOID ESAL_PR_TMR_OS_Timer_Start (UINT32 ticks_per_sec)

Description

This function starts the OS timer at the processor level. This may include determining therequired timer count for the specified period, enabling the timer to produce this period, andenabling the interrupt associated with this timer. The generic macro ESAL_GE_TMR_COUNT_CALC is called to calculate the timer count value for a timer with a given clock rate,clock prescale and period.

Functions Called

ESAL_GE_TMR_COUNT_CALC

ESAL ComponentDevelopment Platform Specific Component (DP)


Development Platform Specific Component (DP)The ESAL development platform component (DP) is responsible for performing any operationsspecific to the development platform (target board). Typically, DP functions relate to memory,interrupt control, interrupt servicing, stacks, and timers.

Development Platform Specific Component FilesThe ESAL development platform component consists of the files defined in the following table.

Table 5-14.

File Description

esal_entry_a.<s> This special purpose file provides the entry pointinto the ESAL code that executes after hardwarepower up or reset.

esal_entry_defs.inc This file is contains any constants, macros, etc,used by the esal_entry function after reset.

esal_dp_cfg.h This file contains required configuration settingsfor the target development platform. Othercomponents may refer to these settings.

esal_dp_int_defs.h This file contains development platform specificdefinitions, structures, assembly macros, etc.,related to interrupt control.

esal_dp_isr_defs.h This file contains development platform specificdefinitions, structures, assembly macros, etc.,related to interrupt servicing.

esal_dp_int.c This file contains development platform specificfunctions related to interrupt control.

esal_dp_isr.c This file contains development platform specificfunctions related to interrupt servicing.

esal_dp_mem.c This file contains development platform specificfunctions related to memory.


ESAL ComponentDevelopment Platform Specific Component (DP)

December 15, 2006

Development Platform Specific Component DataStructures

System Memory RegionsAll the memory regions in the system are described by the array ESAL_DP_MEM_Region_Data. This is an array of ESAL_GE_MEM_REGION data structures.

If a cache is available on the target hardware, this array will be used to configure the cached anduncached regions of memory (based on the cache type).

NoteThis array may be used for numerous purposes within an operating system. Inaccuratedata within this table may cause unexpected results or software failure.

Number of System Memory RegionsESAL_DP_MEM_NUM_REGIONS is defined to be the number of development platformmemory regions found in ESAL_DP_MEM_Region_Data.

Development Platform Specific Component FunctionsThe following sections provide a brief description of the functions in the DP component.Review of the actual source code is recommended for further information.

ESAL ComponentESAL_Entry


ESAL_EntryUsage

VOID ESAL_Entry (VOID)

Description

This function is the entry point into ESAL. Entry to this function is normally done through thetarget’s reset mechanism (i.e. reset vector, jump from reset handler, etc.).

When running from RAM (debug environment), this function does only the minimal amountnecessary to place the processor into the initialization state. The rest of the target initializationis normally completed by a debugger run script or a boot monitor executing on the target.

When running from ROM, this function initializes the memory interfaced to the targetprocessor. This includes initializing chip-selects, SDRAM controllers, and any other memoryrelated hardware. The code to support running from ROM is executed based on the value of theconst variable ESAL_GE_MEM_ROM_Support_Enabled.

The ROM support code should initialize memory controllers, chip-selects, etc., to allow accessto volatile memory (RAM) when running from ROM. Access to this memory must be donebefore entering a C environment so that stacks can be set up and utilized for function calls. Afterinitializing memory, a jump (or branch) is made to enter the initialization function ESAL_AR_STK_Startup_SP_Set. Control does not return to this function. See the ESAL initializationflow chart at the end of this chapter.

Functions Called

ESAL_AR_STK_Startup_SP_Set


ESAL ComponentESAL_DP_INT_All_Disable

December 15, 2006

ESAL_DP_INT_All_DisableUsage

VOID ESAL_DP_INT_All_Disable (VOID)

Description

This function disables all interrupt sources for the given development platform. It sets thevalues for development platform interrupt controller registers (mask registers, priority register,pending registers, etc.) to disable all interrupt sources.

This function is included only if the conditional below, contained in esal_dp_cfg.h, is defined asESAL_TRUE.

ESAL_DP_INTERRUPTS_AVAILABLE

ESAL ComponentESAL_DP_INT_Enable


ESAL_DP_INT_EnableUsage

VOID ESAL_DP_INT_Enable (INT vector_id, ESAL_GE_INT_TRIG_TYPE trigger_type,INT priority)

Description

This function enables the given interrupt source with the specified attributes (if applicable to thegiven development platform).

This function is included only if the following conditional, contained in esal_dp_cfg.h, isdefined as ESAL_TRUE.


Functions Called

Development Platform specific


ESAL ComponentESAL_DP_INT_Disable

December 15, 2006

ESAL_DP_INT_DisableUsage

VOID ESAL_DP_INT_Disable (INT vector_id)

Description




ESAL ComponentESAL_DP_ISR_<Interrupt_Type>_Handler


ESAL_DP_ISR_<Interrupt_Type>_HandlerUsage

static VOID ESAL_DP_ISR_<Interrupt_Type>_Handler (INT vector)

Description

This function is responsible for handling certain development platform level interrupts that wereregistered during initialization. This function performs the minimum number of steps requiredto enable calling the specific development platform interrupt service routine. In general, thisfunction will:

• Determine the interrupt vector ID

• Perform necessary procedures to allow nesting of interrupts

• Re-enable only the interrupts required to allow interrupt nesting

• Execute the ISR for this interrupt by invokingESAL_GE_ISR_HANDLER_EXECUTE.

• Perform necessary procedures to allow recovery from nesting of interrupts



Functions Called

ESAL_GE_ISR_HANDLER_EXECUTE


ESAL ComponentESAL_DP_ISR_Initialize

December 15, 2006

ESAL_DP_ISR_InitializeUsage

VOID ESAL_DP_ISR_Initialize (VOID)

Description

This function is the development platform ISR initialization function. It is responsible forregistering ISRs for development platform related interrupts. This function also initializes thedevelopment platform as necessary to support interrupt servicing.

This function is included only if the following conditional, contained in esal_pr_cfg.h, isdefined as ESAL_TRUE.


Functions Called


Summary Flow ChartsThe following flow charts summarize the ESAL initialization (reset), and low-level interruptsequence.

ESAL ComponentSummary Flow Charts


Figure 5-8. ESAL Initialization (Reset) Sequence


ESAL ComponentSummary Flow Charts

December 15, 2006

Figure 5-9. ESAL Low-Level Interrupt Sequence

End-User License AgreementThe latest version of the End-User License Agreement is available on-line at:

www.mentor.com/terms_conditions/enduser.cfm

END-USER LICENSE AGREEMENT (“Agreement”)

This is a legal agreement concerning the use of Software between you, the end user, as an authorizedrepresentative of the company acquiring the license, and Mentor Graphics Corporation and Mentor Graphics(Ireland) Limited acting directly or through their subsidiaries (collectively “Mentor Graphics”). Except for licenseagreements related to the subject matter of this license agreement which are physically signed by you and anauthorized representative of Mentor Graphics, this Agreement and the applicable quotation contain the parties'entire understanding relating to the subject matter and supersede all prior or contemporaneous agreements. If youdo not agree to these terms and conditions, promptly return or, if received electronically, certify destruction ofSoftware and all accompanying items within five days after receipt of Software and receive a full refund of anylicense fee paid.

1. GRANT OF LICENSE. The software programs, including any updates, modifications, revisions, copies, documentationand design data (“Software”), are copyrighted, trade secret and confidential information of Mentor Graphics or itslicensors who maintain exclusive title to all Software and retain all rights not expressly granted by this Agreement.Mentor Graphics grants to you, subject to payment of appropriate license fees, a nontransferable, nonexclusive license touse Software solely: (a) in machine-readable, object-code form; (b) for your internal business purposes; (c) for the licenseterm; and (d) on the computer hardware and at the site authorized by Mentor Graphics. A site is restricted to a one-halfmile (800 meter) radius. Mentor Graphics’ standard policies and programs, which vary depending on Software, licensefees paid or services purchased, apply to the following: (a) relocation of Software; (b) use of Software, which may belimited, for example, to execution of a single session by a single user on the authorized hardware or for a restricted periodof time (such limitations may be technically implemented through the use of authorization codes or similar devices); and(c) support services provided, including eligibility to receive telephone support, updates, modifications, and revisions.

2. EMBEDDED SOFTWARE. If you purchased a license to use embedded software development (“ESD”) Software, ifapplicable, Mentor Graphics grants to you a nontransferable, nonexclusive license to reproduce and distribute executablefiles created using ESD compilers, including the ESD run-time libraries distributed with ESD C and C++ compilerSoftware that are linked into a composite program as an integral part of your compiled computer program, provided thatyou distribute these files only in conjunction with your compiled computer program. Mentor Graphics does NOT grantyou any right to duplicate, incorporate or embed copies of Mentor Graphics' real-time operating systems or otherembedded software products into your products or applications without first signing or otherwise agreeing to a separateagreement with Mentor Graphics for such purpose.

3. BETA CODE. Software may contain code for experimental testing and evaluation (“Beta Code”), which may not be usedwithout Mentor Graphics’ explicit authorization. Upon Mentor Graphics’ authorization, Mentor Graphics grants to you atemporary, nontransferable, nonexclusive license for experimental use to test and evaluate the Beta Code without chargefor a limited period of time specified by Mentor Graphics. This grant and your use of the Beta Code shall not be construedas marketing or offering to sell a license to the Beta Code, which Mentor Graphics may choose not to releasecommercially in any form. If Mentor Graphics authorizes you to use the Beta Code, you agree to evaluate and test theBeta Code under normal conditions as directed by Mentor Graphics. You will contact Mentor Graphics periodicallyduring your use of the Beta Code to discuss any malfunctions or suggested improvements. Upon completion of yourevaluation and testing, you will send to Mentor Graphics a written evaluation of the Beta Code, including its strengths,weaknesses and recommended improvements. You agree that any written evaluations and all inventions, productimprovements, modifications or developments that Mentor Graphics conceived or made during or subsequent to thisAgreement, including those based partly or wholly on your feedback, will be the exclusive property of Mentor Graphics.Mentor Graphics will have exclusive rights, title and interest in all such property. The provisions of this section 3 shallsurvive the termination or expiration of this Agreement.

IMPORTANT INFORMATION

USE OF THIS SOFTWARE IS SUBJECT TO LICENSE RESTRICTIONS. CAREFULLY READ THISLICENSE AGREEMENT BEFORE USING THE SOFTWARE. USE OF SOFTWARE INDICATES YOURCOMPLETE AND UNCONDITIONAL ACCEPTANCE OF THE TERMS AND CONDITIONS SET FORTH

IN THIS AGREEMENT. ANY ADDITIONAL OR DIFFERENT PURCHASE ORDER TERMS ANDCONDITIONS SHALL NOT APPLY.

http://www.mentor.com/terms_conditions/enduser.cfm

4. RESTRICTIONS ON USE. You may copy Software only as reasonably necessary to support the authorized use. Eachcopy must include all notices and legends embedded in Software and affixed to its medium and container as received fromMentor Graphics. All copies shall remain the property of Mentor Graphics or its licensors. You shall maintain a record ofthe number and primary location of all copies of Software, including copies merged with other software, and shall makethose records available to Mentor Graphics upon request. You shall not make Software available in any form to anyperson other than employees and on-site contractors, excluding Mentor Graphics' competitors, whose job performancerequires access and who are under obligations of confidentiality. You shall take appropriate action to protect theconfidentiality of Software and ensure that any person permitted access to Software does not disclose it or use it except aspermitted by this Agreement. Except as otherwise permitted for purposes of interoperability as specified by applicableand mandatory local law, you shall not reverse-assemble, reverse-compile, reverse-engineer or in any way derive fromSoftware any source code. You may not sublicense, assign or otherwise transfer Software, this Agreement or the rightsunder it, whether by operation of law or otherwise (“attempted transfer”), without Mentor Graphics’ prior written consentand payment of Mentor Graphics’ then-current applicable transfer charges. Any attempted transfer without MentorGraphics' prior written consent shall be a material breach of this Agreement and may, at Mentor Graphics' option, result inthe immediate termination of the Agreement and licenses granted under this Agreement. The terms of this Agreement,including without limitation, the licensing and assignment provisions shall be binding upon your successors in interestand assigns. The provisions of this section 4 shall survive the termination or expiration of this Agreement.

5. LIMITED WARRANTY.

5.1. Mentor Graphics warrants that during the warranty period Software, when properly installed, will substantiallyconform to the functional specifications set forth in the applicable user manual. Mentor Graphics does not warrantthat Software will meet your requirements or that operation of Software will be uninterrupted or error free. Thewarranty period is 90 days starting on the 15th day after delivery or upon installation, whichever first occurs. Youmust notify Mentor Graphics in writing of any nonconformity within the warranty period. This warranty shall not bevalid if Software has been subject to misuse, unauthorized modification or improper installation. MENTORGRAPHICS' ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL BE, AT MENTOR GRAPHICS'OPTION, EITHER (A) REFUND OF THE PRICE PAID UPON RETURN OF SOFTWARE TO MENTORGRAPHICS OR (B) MODIFICATION OR REPLACEMENT OF SOFTWARE THAT DOES NOT MEET THISLIMITED WARRANTY, PROVIDED YOU HAVE OTHERWISE COMPLIED WITH THIS AGREEMENT.MENTOR GRAPHICS MAKES NO WARRANTIES WITH RESPECT TO: (A) SERVICES; (B) SOFTWAREWHICH IS LICENSED TO YOU FOR A LIMITED TERM OR LICENSED AT NO COST; OR(C) EXPERIMENTAL BETA CODE; ALL OF WHICH ARE PROVIDED “AS IS.”

5.2. THE WARRANTIES SET FORTH IN THIS SECTION 5 ARE EXCLUSIVE. NEITHER MENTOR GRAPHICSNOR ITS LICENSORS MAKE ANY OTHER WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, WITHRESPECT TO SOFTWARE OR OTHER MATERIAL PROVIDED UNDER THIS AGREEMENT. MENTORGRAPHICS AND ITS LICENSORS SPECIFICALLY DISCLAIM ALL IMPLIED WARRANTIES OFMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT OFINTELLECTUAL PROPERTY.

6. LIMITATION OF LIABILITY. EXCEPT WHERE THIS EXCLUSION OR RESTRICTION OF LIABILITYWOULD BE VOID OR INEFFECTIVE UNDER APPLICABLE LAW, IN NO EVENT SHALL MENTOR GRAPHICSOR ITS LICENSORS BE LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES(INCLUDING LOST PROFITS OR SAVINGS) WHETHER BASED ON CONTRACT, TORT OR ANY OTHERLEGAL THEORY, EVEN IF MENTOR GRAPHICS OR ITS LICENSORS HAVE BEEN ADVISED OF THEPOSSIBILITY OF SUCH DAMAGES. IN NO EVENT SHALL MENTOR GRAPHICS' OR ITS LICENSORS'LIABILITY UNDER THIS AGREEMENT EXCEED THE AMOUNT PAID BY YOU FOR THE SOFTWARE ORSERVICE GIVING RISE TO THE CLAIM. IN THE CASE WHERE NO AMOUNT WAS PAID, MENTORGRAPHICS AND ITS LICENSORS SHALL HAVE NO LIABILITY FOR ANY DAMAGES WHATSOEVER. THEPROVISIONS OF THIS SECTION 6 SHALL SURVIVE THE EXPIRATION OR TERMINATION OF THISAGREEMENT.

7. LIFE ENDANGERING ACTIVITIES. NEITHER MENTOR GRAPHICS NOR ITS LICENSORS SHALL BELIABLE FOR ANY DAMAGES RESULTING FROM OR IN CONNECTION WITH THE USE OF SOFTWARE INANY APPLICATION WHERE THE FAILURE OR INACCURACY OF THE SOFTWARE MIGHT RESULT INDEATH OR PERSONAL INJURY. THE PROVISIONS OF THIS SECTION 7 SHALL SURVIVE THEEXPIRATION OR TERMINATION OF THIS AGREEMENT.

8. INDEMNIFICATION. YOU AGREE TO INDEMNIFY AND HOLD HARMLESS MENTOR GRAPHICS AND ITSLICENSORS FROM ANY CLAIMS, LOSS, COST, DAMAGE, EXPENSE, OR LIABILITY, INCLUDINGATTORNEYS' FEES, ARISING OUT OF OR IN CONNECTION WITH YOUR USE OF SOFTWARE AS

DESCRIBED IN SECTION 7. THE PROVISIONS OF THIS SECTION 8 SHALL SURVIVE THE EXPIRATION ORTERMINATION OF THIS AGREEMENT.

9. INFRINGEMENT.

9.1. Mentor Graphics will defend or settle, at its option and expense, any action brought against you alleging thatSoftware infringes a patent or copyright or misappropriates a trade secret in the United States, Canada, Japan, ormember state of the European Patent Office. Mentor Graphics will pay any costs and damages finally awardedagainst you that are attributable to the infringement action. You understand and agree that as conditions to MentorGraphics' obligations under this section you must: (a) notify Mentor Graphics promptly in writing of the action;(b) provide Mentor Graphics all reasonable information and assistance to defend or settle the action; and (c) grantMentor Graphics sole authority and control of the defense or settlement of the action.

9.2. If an infringement claim is made, Mentor Graphics may, at its option and expense: (a) replace or modify Software sothat it becomes noninfringing; (b) procure for you the right to continue using Software; or (c) require the return ofSoftware and refund to you any license fee paid, less a reasonable allowance for use.

9.3. Mentor Graphics has no liability to you if infringement is based upon: (a) the combination of Software with anyproduct not furnished by Mentor Graphics; (b) the modification of Software other than by Mentor Graphics; (c) theuse of other than a current unaltered release of Software; (d) the use of Software as part of an infringing process; (e) aproduct that you make, use or sell; (f) any Beta Code contained in Software; (g) any Software provided by MentorGraphics’ licensors who do not provide such indemnification to Mentor Graphics’ customers; or (h) infringement byyou that is deemed willful. In the case of (h) you shall reimburse Mentor Graphics for its attorney fees and other costsrelated to the action upon a final judgment.

9.4. THIS SECTION IS SUBJECT TO SECTION 6 ABOVE AND STATES THE ENTIRE LIABILITY OF MENTORGRAPHICS AND ITS LICENSORS AND YOUR SOLE AND EXCLUSIVE REMEDY WITH RESPECT TOANY ALLEGED PATENT OR COPYRIGHT INFRINGEMENT OR TRADE SECRET MISAPPROPRIATIONBY ANY SOFTWARE LICENSED UNDER THIS AGREEMENT.

10. TERM. This Agreement remains effective until expiration or termination. This Agreement will immediately terminateupon notice if you exceed the scope of license granted or otherwise fail to comply with the provisions of Sections 1, 2, or4. For any other material breach under this Agreement, Mentor Graphics may terminate this Agreement upon 30 dayswritten notice if you are in material breach and fail to cure such breach within the 30 day notice period. If Software wasprovided for limited term use, this Agreement will automatically expire at the end of the authorized term. Upon anytermination or expiration, you agree to cease all use of Software and return it to Mentor Graphics or certify deletion anddestruction of Software, including all copies, to Mentor Graphics’ reasonable satisfaction.

11. EXPORT. Software is subject to regulation by local laws and United States government agencies, which prohibit exportor diversion of certain products, information about the products, and direct products of the products to certain countriesand certain persons. You agree that you will not export any Software or direct product of Software in any manner withoutfirst obtaining all necessary approval from appropriate local and United States government agencies.

12. RESTRICTED RIGHTS NOTICE. Software was developed entirely at private expense and is commercial computersoftware provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the U.S. Government or a U.S.Government subcontractor is subject to the restrictions set forth in the license agreement under which Software wasobtained pursuant to DFARS 227.7202-3(a) or as set forth in subparagraphs (c)(1) and (2) of the Commercial ComputerSoftware - Restricted Rights clause at FAR 52.227-19, as applicable. Contractor/manufacturer is Mentor GraphicsCorporation, 8005 SW Boeckman Road, Wilsonville, Oregon 97070-7777 USA.

13. THIRD PARTY BENEFICIARY. For any Software under this Agreement licensed by Mentor Graphics from Microsoftor other licensors, Microsoft or the applicable licensor is a third party beneficiary of this Agreement with the right toenforce the obligations set forth herein.

14. AUDIT RIGHTS. You will monitor access to, location and use of Software. With reasonable prior notice and duringyour normal business hours, Mentor Graphics shall have the right to review your software monitoring system andreasonably relevant records to confirm your compliance with the terms of this Agreement, an addendum to thisAgreement or U.S. or other local export laws. Such review may include FLEXlm or FLEXnet report log files that youshall capture and provide at Mentor Graphics’ request. Mentor Graphics shall treat as confidential information all of yourinformation gained as a result of any request or review and shall only use or disclose such information as required by lawor to enforce its rights under this Agreement or addendum to this Agreement. The provisions of this section 14 shallsurvive the expiration or termination of this Agreement.

15. CONTROLLING LAW, JURISDICTION AND DISPUTE RESOLUTION. THIS AGREEMENT SHALL BEGOVERNED BY AND CONSTRUED UNDER THE LAWS OF THE STATE OF OREGON, USA, IF YOU ARELOCATED IN NORTH OR SOUTH AMERICA, AND THE LAWS OF IRELAND IF YOU ARE LOCATEDOUTSIDE OF NORTH OR SOUTH AMERICA. All disputes arising out of or in relation to this Agreement shall besubmitted to the exclusive jurisdiction of Portland, Oregon when the laws of Oregon apply, or Dublin, Ireland when thelaws of Ireland apply. Notwithstanding the foregoing, all disputes in Asia (except for Japan) arising out of or in relation tothis Agreement shall be resolved by arbitration in Singapore before a single arbitrator to be appointed by the Chairman ofthe Singapore International Arbitration Centre (“SIAC”) to be conducted in the English language, in accordance with theArbitration Rules of the SIAC in effect at the time of the dispute, which rules are deemed to be incorporated by referencein this section 15. This section shall not restrict Mentor Graphics’ right to bring an action against you in the jurisdictionwhere your place of business is located. The United Nations Convention on Contracts for the International Sale of Goodsdoes not apply to this Agreement.

16. SEVERABILITY. If any provision of this Agreement is held by a court of competent jurisdiction to be void, invalid,unenforceable or illegal, such provision shall be severed from this Agreement and the remaining provisions will remain infull force and effect.

17. PAYMENT TERMS AND MISCELLANEOUS. You will pay amounts invoiced, in the currency specified on theapplicable invoice, within 30 days from the date of such invoice. Any past due invoices will be subject to the impositionof interest charges in the amount of one and one-half percent per month or the applicable legal rate currently in effect,whichever is lower. Some Software may contain code distributed under a third party license agreement that may provideadditional rights to you. Please see the applicable Software documentation for details. This Agreement may only bemodified in writing by authorized representatives of the parties. Waiver of terms or excuse of breach must be in writingand shall not constitute subsequent consent, waiver or excuse.

Rev. 060210, Part No. 227900

Documents

read.pudn.comread.pudn.com/downloads178/ebook/827709/tech... · Nucleus PLUS Internals Manual Software Version 2.1 Part Number 0001027-001 December 15, 2006 Document Revision 301