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.
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
Nucleus PLUS Internals Manual, Software Version 2.1 5December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
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
Nucleus PLUS Internals Manual, Software Version 2.1 7December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
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
Nucleus PLUS Internals Manual, Software Version 2.1 9December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
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
Nucleus PLUS Internals Manual, Software Version 2.1 11December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
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
Nucleus PLUS Internals Manual, Software Version 2.1 13December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
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
Nucleus PLUS Internals Manual, Software Version 2.1 15December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
End-User License Agreement
Nucleus PLUS Internals Manual, Software Version 2.1 17December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1
Nucleus PLUS Internals Manual, Software Version 2.1 19December 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.
Nucleus PLUS Internals Manual, Software Version 2.120
IntroductionNucleus PLUS Construction
December 15, 2006
Nucleus PLUS Internals Manual, Software Version 2.1 21December 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.
Nucleus PLUS Internals Manual, Software Version 2.122
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
Nucleus PLUS Internals Manual, Software Version 2.1 23December 15, 2006
* 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]*
Nucleus PLUS Internals Manual, Software Version 2.124
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
Implementation ConventionsNaming Conventions
Nucleus PLUS Internals Manual, Software Version 2.1 25December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.126
Implementation ConventionsNaming Conventions
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.
Example (for the ex_defs.h file):
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.
Example (for the ex_defs.h file):
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.
Example (for the ex_defs.h file):
struct EX_MY_STRUCT{ INT ex_member_a; INT ex_member_b; INT ex_member_c;};
Implementation ConventionsNaming Conventions
Nucleus PLUS Internals Manual, Software Version 2.1 27December 15, 2006
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.
Example (for the exd.c file):
/* 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.
Example (for the exd.c file):
VOID EXD_My_Function(UNSIGNED i){ . . .}
Nucleus PLUS Internals Manual, Software Version 2.128
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.
Example (for the exd.c file):
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. */
Nucleus PLUS Internals Manual, Software Version 2.1 29December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.130
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.
Software OverviewData Types
Nucleus PLUS Internals Manual, Software Version 2.1 31December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.132
Software OverviewData Types
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
Software OverviewData Types
Nucleus PLUS Internals Manual, Software Version 2.1 33December 15, 2006
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_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.)
Nucleus PLUS Service Internal Function
Nucleus PLUS Internals Manual, Software Version 2.134
Software OverviewData Types
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
Table 3-3. NU_ERROR_CHECKING = NU_TRUE Default Mappings (cont.)
Nucleus PLUS Service Internal Function
Software OverviewData Types
Nucleus PLUS Internals Manual, Software Version 2.1 35December 15, 2006
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
Nucleus PLUS Service Internal Function
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
Table 3-3. NU_ERROR_CHECKING = NU_TRUE Default Mappings (cont.)
Nucleus PLUS Service Internal Function
Nucleus PLUS Internals Manual, Software Version 2.136
Software OverviewData Types
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_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
Table 3-4. NU_ERROR_CHECKING=NU_FALSE Default Mappings (cont.)
Nucleus PLUS Service Internal Function
Software OverviewData Types
Nucleus PLUS Internals Manual, Software Version 2.1 37December 15, 2006
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
Table 3-4. NU_ERROR_CHECKING=NU_FALSE Default Mappings (cont.)
Nucleus PLUS Service Internal Function
Nucleus PLUS Internals Manual, Software Version 2.138
Software OverviewData Types
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
Table 3-4. NU_ERROR_CHECKING=NU_FALSE Default Mappings (cont.)
Nucleus PLUS Service Internal Function
Software OverviewData Types
Nucleus PLUS Internals Manual, Software Version 2.1 39December 15, 2006
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
Table 3-4. NU_ERROR_CHECKING=NU_FALSE Default Mappings (cont.)
Nucleus PLUS Service Internal Function
Nucleus PLUS Internals Manual, Software Version 2.140
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.
Nucleus PLUS Internals Manual, Software Version 2.1 41December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.142
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
Nucleus PLUS Internals Manual, Software Version 2.1 43December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.144
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
Nucleus PLUS Internals Manual, Software Version 2.1 45December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.146
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
Nucleus PLUS Internals Manual, Software Version 2.1 47December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.148
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
Nucleus PLUS Internals Manual, Software Version 2.1 49December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.150
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
Component DescriptionsNucleus Middleware Initialization Component (NMI)
Nucleus PLUS Internals Manual, Software Version 2.1 51December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.152
Component DescriptionsNucleus Middleware Initialization Component (NMI)
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
Component DescriptionsNucleus Middleware Initialization Component (NMI)
Nucleus PLUS Internals Manual, Software Version 2.1 53December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.154
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
Nucleus PLUS Internals Manual, Software Version 2.1 55December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.156
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
Nucleus PLUS Internals Manual, Software Version 2.1 57December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.158
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
Nucleus PLUS Internals Manual, Software Version 2.1 59December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.160
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
Nucleus PLUS Internals Manual, Software Version 2.1 61December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.162
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
NMI_Product_Data_Find
Component DescriptionsNMI_Wait_For_Init
Nucleus PLUS Internals Manual, Software Version 2.1 63December 15, 2006
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
NMI_Product_Data_Find
NU_Sleep
Nucleus PLUS Internals Manual, Software Version 2.164
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
NMI_Product_Data_Find
Component DescriptionsNMI_Product_Data_Find
Nucleus PLUS Internals Manual, Software Version 2.1 65December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.166
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
Nucleus PLUS Internals Manual, Software Version 2.1 67December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.168
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
Nucleus PLUS Internals Manual, Software Version 2.1 69December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.170
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
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 71December 15, 2006
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.)
Nucleus PLUS Internals Manual, Software Version 2.172
Component DescriptionsThread Control Component (TC)
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.)
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 73December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.174
Component DescriptionsThread Control Component (TC)
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.
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 75December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.176
Component DescriptionsThread Control Component (TC)
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.
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 77December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.178
Component DescriptionsThread Control Component (TC)
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
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.
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 79December 15, 2006
Field Declarations
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
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.
Nucleus PLUS Internals Manual, Software Version 2.180
Component DescriptionsThread Control Component (TC)
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.
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 81December 15, 2006
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.)
Nucleus PLUS Internals Manual, Software Version 2.182
Component DescriptionsThread Control Component (TC)
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_system_reserved_2 This is a reserved word for use by the system.
tc_system_reserved_3 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.)
Component DescriptionsThread Control Component (TC)
Nucleus PLUS Internals Manual, Software Version 2.1 83December 15, 2006
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_not_used_2 This field is a placeholder and is not used.
tc_priority This is the priority of the HISR.
tc_not_used_3 This field is a placeholder and is not used.
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_system_reserved_1 This is a reserved word for use by the system.
tc_system_reserved_2 This is a reserved word for use by the system.
tc_system_reserved_3 This is a reserved word for use by the system.
tc_app_reserved_1 This is a reserved word for use by the application.
Nucleus PLUS Internals Manual, Software Version 2.184
Component DescriptionsThread Control Component (TC)
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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.
tc_thread_waiting A flag indicating that one or more threads are waiting for the protection.
Component DescriptionsTCCT_Create_Task
Nucleus PLUS Internals Manual, Software Version 2.1 85December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.186
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCCT_Create_HISR
Nucleus PLUS Internals Manual, Software Version 2.1 87December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
[MSC_Bind_Module_HISR]
ESAL_TS_STK_Solicited_Set
Nucleus PLUS Internals Manual, Software Version 2.188
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCCT_Reset_Task
Nucleus PLUS Internals Manual, Software Version 2.1 89December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
ESAL_AR_STK_Unsolicited_Set
Nucleus PLUS Internals Manual, Software Version 2.190
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
TCCT_Unprotect_Specific
TMC_Stop_Task_Timer
Component DescriptionsTCC_Resume_Task
Nucleus PLUS Internals Manual, Software Version 2.1 91December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.192
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
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCC_Suspend_Task
Nucleus PLUS Internals Manual, Software Version 2.1 93December 15, 2006
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_Control_To_System
TCCT_Protect
TCCT_Set_Execute_Task
TCCT_Protect_Switch
TCCT_Unprotect
TMC_Start_Task_Timer
Nucleus PLUS Internals Manual, Software Version 2.194
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCC_Task_Timeout
Nucleus PLUS Internals Manual, Software Version 2.1 95December 15, 2006
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_Set_Current_Protect
TCCT_Unprotect
TCCT_Unprotect_Specific
Nucleus PLUS Internals Manual, Software Version 2.196
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCC_Relinquish
Nucleus PLUS Internals Manual, Software Version 2.1 97December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Set_Execute_Task
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.198
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_Set_Execute_Task
TCCT_Unprotect
Component DescriptionsTCC_Current_Task_Pointer
Nucleus PLUS Internals Manual, Software Version 2.1 99December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1100
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
Nucleus PLUS Internals Manual, Software Version 2.1 101December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1102
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_Set_Execute_Task
TCCT_Unprotect
Component DescriptionsTCC_Unhandled_Interrupt
Nucleus PLUS Internals Manual, Software Version 2.1 103December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1104
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
Nucleus PLUS Internals Manual, Software Version 2.1 105December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1106
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
Nucleus PLUS Internals Manual, Software Version 2.1 107December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1108
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
Nucleus PLUS Internals Manual, Software Version 2.1 109December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1110
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
Nucleus PLUS Internals Manual, Software Version 2.1 111December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1112
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
Nucleus PLUS Internals Manual, Software Version 2.1 113December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1114
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
Nucleus PLUS Internals Manual, Software Version 2.1 115December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1116
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
Nucleus PLUS Internals Manual, Software Version 2.1 117December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1118
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
Nucleus PLUS Internals Manual, Software Version 2.1 119December 15, 2006
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_Set_Current_Protect
TCCT_Get_Current_Protect
TCCT_System_Protect
TCCT_System_Unprotect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1120
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
Nucleus PLUS Internals Manual, Software Version 2.1 121December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1122
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
Nucleus PLUS Internals Manual, Software Version 2.1 123December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1124
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
Nucleus PLUS Internals Manual, Software Version 2.1 125December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1126
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
Nucleus PLUS Internals Manual, Software Version 2.1 127December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Set_Execute_Task
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1128
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Set_Execute_Task
TCCT_Unprotect
Component DescriptionsTCS_Change_Time_Slice
Nucleus PLUS Internals Manual, Software Version 2.1 129December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1130
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
[HIC_Make_History_Entry]
TCC_Signal_Shell
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCS_Receive_Signals
Nucleus PLUS Internals Manual, Software Version 2.1 131December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1132
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
[HIC_Make_History_Entry]
TCC_Signal_Shell
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsTCST_Send_Signals
Nucleus PLUS Internals Manual, Software Version 2.1 133December 15, 2006
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
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Signal_Shell
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Unprotect
ESAL_TS_STK_Solicited_Set
Nucleus PLUS Internals Manual, Software Version 2.1134
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
Nucleus PLUS Internals Manual, Software Version 2.1 135December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1136
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
Nucleus PLUS Internals Manual, Software Version 2.1 137December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1138
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
Nucleus PLUS Internals Manual, Software Version 2.1 139December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1140
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
Nucleus PLUS Internals Manual, Software Version 2.1 141December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1142
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
Nucleus PLUS Internals Manual, Software Version 2.1 143December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1144
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
Nucleus PLUS Internals Manual, Software Version 2.1 145December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1146
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
Nucleus PLUS Internals Manual, Software Version 2.1 147December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1148
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
ESAL_TS_STK_Solicited_Switch
Component DescriptionsTCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1 149December 15, 2006
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
ESAL_TS_STK_Solicited_Switch
Nucleus PLUS Internals Manual, Software Version 2.1150
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
ESAL_TS_STK_Solicited_Switch
Component DescriptionsTCCT_Set_Current_Protect
Nucleus PLUS Internals Manual, Software Version 2.1 151December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1152
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
Nucleus PLUS Internals Manual, Software Version 2.1 153December 15, 2006
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
ESAL_TS_STK_Solicited_Switch
Nucleus PLUS Internals Manual, Software Version 2.1154
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
Nucleus PLUS Internals Manual, Software Version 2.1 155December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1156
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
Nucleus PLUS Internals Manual, Software Version 2.1 157December 15, 2006
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
ESAL_TS_STK_Solicited_Set
TCCT_Schedule
Nucleus PLUS Internals Manual, Software Version 2.1158
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)
Nucleus PLUS Internals Manual, Software Version 2.1 159December 15, 2006
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
Field Summary
Table 4-20.
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.
Nucleus PLUS Internals Manual, Software Version 2.1160
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.
Component DescriptionsActive Timers List
Nucleus PLUS Internals Manual, Software Version 2.1 161December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1162
Component DescriptionsActive Timers List
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.
Component DescriptionsActive Timers List
Nucleus PLUS Internals Manual, Software Version 2.1 163December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1164
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
Nucleus PLUS Internals Manual, Software Version 2.1 165December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1166
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
Nucleus PLUS Internals Manual, Software Version 2.1 167December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1168
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
Nucleus PLUS Internals Manual, Software Version 2.1 169December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1170
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
Nucleus PLUS Internals Manual, Software Version 2.1 171December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1172
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
Nucleus PLUS Internals Manual, Software Version 2.1 173December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1174
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
HIC_Make_History_Entry
TCCT_Check_Stack
TCCT_Protect
TCCT_Unprotect
TMS_Control_Timer
Component DescriptionsTMS_Delete_Timer
Nucleus PLUS Internals Manual, Software Version 2.1 175December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_System_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1176
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_System_Protect
TCCT_Unprotect
TMS_Control_Timer
Component DescriptionsTMS_Control_Timer
Nucleus PLUS Internals Manual, Software Version 2.1 177December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_System_Protect
TCCT_Unprotect
TMC_Start_Timer
TMC_Stop_Timer
Nucleus PLUS Internals Manual, Software Version 2.1178
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
Nucleus PLUS Internals Manual, Software Version 2.1 179December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1180
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
Nucleus PLUS Internals Manual, Software Version 2.1 181December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1182
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
Nucleus PLUS Internals Manual, Software Version 2.1 183December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1184
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
Nucleus PLUS Internals Manual, Software Version 2.1 185December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1186
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
Nucleus PLUS Internals Manual, Software Version 2.1 187December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1188
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
Nucleus PLUS Internals Manual, Software Version 2.1 189December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1190
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
Component DescriptionsMailbox Component (MB)
Nucleus PLUS Internals Manual, Software Version 2.1 191December 15, 2006
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
Field Summary
Table 4-24.
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.
Nucleus PLUS Internals Manual, Software Version 2.1192
Component DescriptionsMailbox Component (MB)
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
Component DescriptionsMailbox Component (MB)
Nucleus PLUS Internals Manual, Software Version 2.1 193December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1194
Component DescriptionsMailbox Component (MB)
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
Nucleus PLUS Internals Manual, Software Version 2.1 195December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1196
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
Component DescriptionsMBC_Send_To_Mailbox
Nucleus PLUS Internals Manual, Software Version 2.1 197December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Nucleus PLUS Internals Manual, Software Version 2.1198
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Component DescriptionsMBC_Cleanup
Nucleus PLUS Internals Manual, Software Version 2.1 199December 15, 2006
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
CSC_Remove_From_List
Nucleus PLUS Internals Manual, Software Version 2.1200
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
Nucleus PLUS Internals Manual, Software Version 2.1 201December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1202
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
Nucleus PLUS Internals Manual, Software Version 2.1 203December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1204
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
Nucleus PLUS Internals Manual, Software Version 2.1 205December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1206
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
Nucleus PLUS Internals Manual, Software Version 2.1 207December 15, 2006
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
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1208
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Component DescriptionsMBSE_Reset_Mailbox
Nucleus PLUS Internals Manual, Software Version 2.1 209December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1210
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)
Nucleus PLUS Internals Manual, Software Version 2.1 211December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1212
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
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.
Component DescriptionsQueue Control Block
Nucleus PLUS Internals Manual, Software Version 2.1 213December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1214
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
Nucleus PLUS Internals Manual, Software Version 2.1 215December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1216
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsQUC_Delete_Queue
Nucleus PLUS Internals Manual, Software Version 2.1 217December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
Nucleus PLUS Internals Manual, Software Version 2.1218
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Component DescriptionsQUC_Receive_From_Queue
Nucleus PLUS Internals Manual, Software Version 2.1 219December 15, 2006
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Nucleus PLUS Internals Manual, Software Version 2.1220
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
CSC_Remove_From_List
Component DescriptionsQUCE_Create_Queue
Nucleus PLUS Internals Manual, Software Version 2.1 221December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1222
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
Nucleus PLUS Internals Manual, Software Version 2.1 223December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1224
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
Nucleus PLUS Internals Manual, Software Version 2.1 225December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1226
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
Nucleus PLUS Internals Manual, Software Version 2.1 227December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1228
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
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Component DescriptionsQUS_Send_To_Front_Of_Queue
Nucleus PLUS Internals Manual, Software Version 2.1 229December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
[TCCT_Check_Stack]
Nucleus PLUS Internals Manual, Software Version 2.1230
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Component DescriptionsQUSE_Reset_Queue
Nucleus PLUS Internals Manual, Software Version 2.1 231December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1232
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
Nucleus PLUS Internals Manual, Software Version 2.1 233December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1234
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
Component DescriptionsPipe Component (PI)
Nucleus PLUS Internals Manual, Software Version 2.1 235December 15, 2006
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
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.
Nucleus PLUS Internals Manual, Software Version 2.1236
Component DescriptionsPipe Component (PI)
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
Component DescriptionsPipe Component (PI)
Nucleus PLUS Internals Manual, Software Version 2.1 237December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1238
Component DescriptionsPipe Component (PI)
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
Nucleus PLUS Internals Manual, Software Version 2.1 239December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1240
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
Component DescriptionsPIC_Send_To_Pipe
Nucleus PLUS Internals Manual, Software Version 2.1 241December 15, 2006
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Nucleus PLUS Internals Manual, Software Version 2.1242
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
TCC_Task_Priority
TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Current_Thread
TCCT_System_Protect
TCCT_Unprotect
Component DescriptionsPIC_Cleanup
Nucleus PLUS Internals Manual, Software Version 2.1 243December 15, 2006
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
CSC_Remove_From_List
Nucleus PLUS Internals Manual, Software Version 2.1244
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
Nucleus PLUS Internals Manual, Software Version 2.1 245December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1246
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
Nucleus PLUS Internals Manual, Software Version 2.1 247December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1248
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
Nucleus PLUS Internals Manual, Software Version 2.1 249December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1250
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
Nucleus PLUS Internals Manual, Software Version 2.1 251December 15, 2006
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
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1252
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Component DescriptionsPIS_Broadcast_To_Pipe
Nucleus PLUS Internals Manual, Software Version 2.1 253December 15, 2006
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
CSC_Priority_Place_On_List
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
TCC_Suspend_Task
Nucleus PLUS Internals Manual, Software Version 2.1254
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
Nucleus PLUS Internals Manual, Software Version 2.1 255December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1256
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)
Nucleus PLUS Internals Manual, Software Version 2.1 257December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1258
Component DescriptionsSemaphore Component (SM)
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
Field Summary
Table 4-36.
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
Component DescriptionsSemaphore Component (SM)
Nucleus PLUS Internals Manual, Software Version 2.1 259December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1260
Component DescriptionsSemaphore Component (SM)
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.
Component DescriptionsSemaphore Component (SM)
Nucleus PLUS Internals Manual, Software Version 2.1 261December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1262
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsSMC_Delete_Semaphore
Nucleus PLUS Internals Manual, Software Version 2.1 263December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
Nucleus PLUS Internals Manual, Software Version 2.1264
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
CSC_Priority_Place_On_List
[HIC_Make_History_Entry]
TCC_Suspend_Task
TCC_Task_Priority
[TCCT_Check_Stack]
TCCT_Current_Thread
TCCT_System_Protect
TCCT_Unprotect
Component DescriptionsSMC_Release_Semaphore
Nucleus PLUS Internals Manual, Software Version 2.1 265December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1266
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
CSC_Remove_From_List
Component DescriptionsSMCE_Create_Semaphore
Nucleus PLUS Internals Manual, Software Version 2.1 267December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1268
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
Nucleus PLUS Internals Manual, Software Version 2.1 269December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1270
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
Nucleus PLUS Internals Manual, Software Version 2.1 271December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1272
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
Nucleus PLUS Internals Manual, Software Version 2.1 273December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1274
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
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Component DescriptionsSMSE_Reset_Semaphore
Nucleus PLUS Internals Manual, Software Version 2.1 275December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1276
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
Component DescriptionsEvent Group Component (EV)
Nucleus PLUS Internals Manual, Software Version 2.1 277December 15, 2006
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.
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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_tcb_pointer Identifies the thread that currently has the protection.
tc_thread_waiting A flag indicating that one or more threads are waiting for protection
Nucleus PLUS Internals Manual, Software Version 2.1278
Component DescriptionsEvent Group Component (EV)
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.
Component DescriptionsEvent Group Component (EV)
Nucleus PLUS Internals Manual, Software Version 2.1 279December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1280
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsEVC_Delete_Event_Group
Nucleus PLUS Internals Manual, Software Version 2.1 281December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Set_Current_ProtectTCCT_System_Protect
TCCT_System_Unprotect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1282
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Component DescriptionsEVC_Retrieve_Events
Nucleus PLUS Internals Manual, Software Version 2.1 283December 15, 2006
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
[TCCT_Check_Stack]
TCCT_Current_Thread
TCCT_System_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1284
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
CSC_Remove_From_List
Component DescriptionsEVCE_Create_Event_Group
Nucleus PLUS Internals Manual, Software Version 2.1 285December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1286
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
Nucleus PLUS Internals Manual, Software Version 2.1 287December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1288
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
Nucleus PLUS Internals Manual, Software Version 2.1 289December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1290
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
Nucleus PLUS Internals Manual, Software Version 2.1 291December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1292
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
Component DescriptionsPartition Memory Component (PM)
Nucleus PLUS Internals Manual, Software Version 2.1 293December 15, 2006
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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.
tc_thread_waiting A flag indicating that one or more threads are waiting for theprotection.
Nucleus PLUS Internals Manual, Software Version 2.1294
Component DescriptionsPartition Memory Component (PM)
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
Component DescriptionsPartition Memory Component (PM)
Nucleus PLUS Internals Manual, Software Version 2.1 295December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1296
Component DescriptionsPartition Memory Component (PM)
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.
Component DescriptionsPartition Memory Component (PM)
Nucleus PLUS Internals Manual, Software Version 2.1 297December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1298
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsPMC_Delete_Partition_Pool
Nucleus PLUS Internals Manual, Software Version 2.1 299December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Set_Current_Protect
TCCT_System_Protect
TCCT_System_Unprotect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1300
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
CSC_Priority_Place_On_List
[HIC_Make_History_Entry]
TCC_Suspend_Task
TCC_Task_Priority
[TCCT_Check_Stack]
TCCT_Current_Thread
TCCT_System_Protect
TCCT_Unprotect
Component DescriptionsPMC_Deallocate_Partition
Nucleus PLUS Internals Manual, Software Version 2.1 301December 15, 2006
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_System_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1302
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
CSC_Remove_From_List
Component DescriptionsPMCE_Create_Partition_Pool
Nucleus PLUS Internals Manual, Software Version 2.1 303December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1304
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
Nucleus PLUS Internals Manual, Software Version 2.1 305December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1306
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
Nucleus PLUS Internals Manual, Software Version 2.1 307December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1308
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
Nucleus PLUS Internals Manual, Software Version 2.1 309December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1310
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
Component DescriptionsDynamic Memory Component (DM)
Nucleus PLUS Internals Manual, Software Version 2.1 311December 15, 2006
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
Nucleus PLUS Internals Manual, Software Version 2.1312
Component DescriptionsDynamic Memory Component (DM)
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
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 the protection.
Component DescriptionsDynamic Memory Component (DM)
Nucleus PLUS Internals Manual, Software Version 2.1 313December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1314
Component DescriptionsDynamic Memory Component (DM)
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.
Component DescriptionsDynamic Memory Component (DM)
Nucleus PLUS Internals Manual, Software Version 2.1 315December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1316
Component DescriptionsDynamic Memory Component (DM)
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
Nucleus PLUS Internals Manual, Software Version 2.1 317December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1318
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Protect
TCCT_Set_Current_Protect
TCCT_System_Protect
TCCT_System_Unprotect
TCCT_Unprotect
Component DescriptionsDMC_Allocate_Memory
Nucleus PLUS Internals Manual, Software Version 2.1 319December 15, 2006
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
TCC_Task_Priority
[TCCT_Check_Stack]
TCCT_Current_Thread
TCCT_Protect
TCCT_Set_Suspend_Protect
TCCT_System_Protect
TCCT_Unprotect
TCCT_Unprotect_Specific
Nucleus PLUS Internals Manual, Software Version 2.1320
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
TCC_Resume_Task
[TCCT_Check_Stack]
TCCT_Control_To_System
TCCT_Set_Current_Protect
TCCT_System_Protect
TCCT_System_Unprotect
TCCT_Protect
TCCT_Unprotect
Component DescriptionsDMC_Cleanup
Nucleus PLUS Internals Manual, Software Version 2.1 321December 15, 2006
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
CSC_Remove_From_List
Nucleus PLUS Internals Manual, Software Version 2.1322
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
Nucleus PLUS Internals Manual, Software Version 2.1 323December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1324
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
TCC_Task_Priority
[TCCT_Check_Stack]
TCCT_Current_Thread
TCCT_Protect
TCCT_Set_Suspend_Protect
TCCT_System_Protect
TCCT_Unprotect
TCCT_Unprotect_Specific
Component DescriptionsDMCE_Allocate_Memory
Nucleus PLUS Internals Manual, Software Version 2.1 325December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1326
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
Nucleus PLUS Internals Manual, Software Version 2.1 327December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1328
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
Nucleus PLUS Internals Manual, Software Version 2.1 329December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1330
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
Component DescriptionsZero Copy Component (ZC)
Nucleus PLUS Internals Manual, Software Version 2.1 331December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1332
Component DescriptionsZero Copy Component (ZC)
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.
Component DescriptionsZero Copy Component (ZC)
Nucleus PLUS Internals Manual, Software Version 2.1 333December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1334
Component DescriptionsZero Copy Component (ZC)
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.
Component DescriptionsZero Copy Component (ZC)
Nucleus PLUS Internals Manual, Software Version 2.1 335December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1336
Component DescriptionsZero Copy Component (ZC)
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
Component DescriptionsZero Copy Component (ZC)
Nucleus PLUS Internals Manual, Software Version 2.1 337December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1338
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
Nucleus PLUS Internals Manual, Software Version 2.1 339December 15, 2006
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.
Functions / Macros Called
ZC_OBJ_PTR_FROM_BUF_ID_GET
ZC_BUF_BEGIN_CHECK
ZC_BUF_END_CHECK
ZC_OBJ_PTR_GET
ZC_Seg_Split
Nucleus PLUS Internals Manual, Software Version 2.1340
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
ZC_OBJ_PTR_FROM_BUF_ID_GET
Component DescriptionsZC_Seg_Data_Remove
Nucleus PLUS Internals Manual, Software Version 2.1 341December 15, 2006
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.
Functions / Macros Called
ZC_OBJ_PTR_FROM_BUF_ID_GET
ZC_OBJ_PTR_GET
ZC_Seg_Split
ZC_Seg_Delete
Nucleus PLUS Internals Manual, Software Version 2.1342
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.
Functions / Macros Called
ZC_OBJ_PTR_FROM_BUF_ID_GET
ZC_OBJ_PTR_GET
ZC_ONE_SEG_CHECK
ZC_Obj_Deallocate
ZC_Data_Ref_Remove
Component DescriptionsZC_Data_Create
Nucleus PLUS Internals Manual, Software Version 2.1 343December 15, 2006
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.
Functions/Macros Called
ZC_Obj_Allocate
ZC_OBJ_PTR_GET
Nucleus PLUS Internals Manual, Software Version 2.1344
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.
Functions/Macros Called
ZC_OBJ_PTR_GET
ZC_Obj_Deallocate
Component DescriptionsZC_Obj_Allocate
Nucleus PLUS Internals Manual, Software Version 2.1 345December 15, 2006
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.
Functions/Macros Called
ZC_GLOBAL_DATA_GET
Nucleus PLUS Internals Manual, Software Version 2.1346
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.
Functions/Macros Called
ZC_OBJ_PTR_GET
ZC_GLOBAL_DATA_GET
Component DescriptionsZC_Mem_Free
Nucleus PLUS Internals Manual, Software Version 2.1 347December 15, 2006
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.
Functions/Macros Called
NU_Deallocate_Memory
Nucleus PLUS Internals Manual, Software Version 2.1348
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)
Functions/Macros Called
ZC_OBJ_PTR_FROM_BUF_ID_GET
ZC_BUF_EMPTY_CHECK
ZC_SEG_NONNULL_ENSURE
Component DescriptionsInput/Output Driver Component
Nucleus PLUS Internals Manual, Software Version 2.1 349December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1350
Component DescriptionsInput/Output Driver Component
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.
Component DescriptionsInput/Output Driver Component
Nucleus PLUS Internals Manual, Software Version 2.1 351December 15, 2006
Field Declarations
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
tc_thread_waiting A flag indicating that one or more threads are waiting for theprotection
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
Nucleus PLUS Internals Manual, Software Version 2.1352
Component DescriptionsInput/Output Driver Component
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
Component DescriptionsInput/Output Driver Component
Nucleus PLUS Internals Manual, Software Version 2.1 353December 15, 2006
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_logical_unit Contains the I/O driver’s logical unit number
nu_assign_info This variable is used for additional I/O driver release information
Nucleus PLUS Internals Manual, Software Version 2.1354
Component DescriptionsInput/Output Driver Component
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_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 output buffer
nu_request_size The requested size of the I/O driver output data
Component DescriptionsInput/Output Driver Component
Nucleus PLUS Internals Manual, Software Version 2.1 355December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1356
Component DescriptionsInput/Output Driver Component
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
Nucleus PLUS Internals Manual, Software Version 2.1 357December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1358
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
CSC_Remove_From_List
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
TCCT_Protect
TCCT_Unprotect
Component DescriptionsIOC_Request_Driver
Nucleus PLUS Internals Manual, Software Version 2.1 359December 15, 2006
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
[HIC_Make_History_Entry]
[TCCT_Check_Stack]
Nucleus PLUS Internals Manual, Software Version 2.1360
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
[HIC_Make_History_Entry]
TCC_Resume_Task
TCCT_Control_To_System
[TCCT_Check_Stack]
TCCT_Get_Current_Protect
TCCT_Set_Current_Protect
TCCT_System_Protect
TCCT_System_Unprotect
TCCT_Unprotect
TCCT_Unprotect_Specific
Component DescriptionsIOC_Suspend_Driver
Nucleus PLUS Internals Manual, Software Version 2.1 361December 15, 2006
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
[HIC_Make_History_Entry]
TCC_Suspend_Task
TCCT_Current_Thread
[TCCT_Check_Stack]
TCCT_Get_Current_Protect
TCCT_Set_Suspend_Protect
TCCT_System_Protect
TCCT_Unprotect_Specific
Nucleus PLUS Internals Manual, Software Version 2.1362
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
Nucleus PLUS Internals Manual, Software Version 2.1 363December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1364
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
Nucleus PLUS Internals Manual, Software Version 2.1 365December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1366
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
Nucleus PLUS Internals Manual, Software Version 2.1 367December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1368
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)
Nucleus PLUS Internals Manual, Software Version 2.1 369December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1370
Component DescriptionsHistory Component (HI)
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
TC_TCB *tc_tcb_pointerUNSIGNED tc_thread_waiting
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
tc_thread_waiting A flag indicating that one or more threads are waiting for theprotection
Component DescriptionsHistory Component (HI)
Nucleus PLUS Internals Manual, Software Version 2.1 371December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1372
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
Nucleus PLUS Internals Manual, Software Version 2.1 373December 15, 2006
HIC_Enable_History_SavingUsage
VOID HIC_Enable_History_Saving (VOID)
Description
This function enables the history saving function.
Functions Called
TCCT_Protect
TCCT_Unprotect
Nucleus PLUS Internals Manual, Software Version 2.1374
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
HIC_Make_History_Entry
Component DescriptionsHIC_Make_History_Entry
Nucleus PLUS Internals Manual, Software Version 2.1 375December 15, 2006
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_Get_Current_Protect
TCCT_Protect
TCCT_Set_Current_Protect
TCCT_Unprotect
TCCT_Unprotect_Specific
TMCT_Retrieve_Clock
Nucleus PLUS Internals Manual, Software Version 2.1376
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)
Nucleus PLUS Internals Manual, Software Version 2.1 377December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1378
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
Nucleus PLUS Internals Manual, Software Version 2.1 379December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1380
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
Nucleus PLUS Internals Manual, Software Version 2.1 381December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1382
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
Nucleus PLUS Internals Manual, Software Version 2.1 383December 15, 2006
NU_CHECKERC_System_ErrorDescription
This macro checks to see if the test is true. When the test is false, the passed in statement isexecuted.
Nucleus PLUS Internals Manual, Software Version 2.1384
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
Nucleus PLUS Internals Manual, Software Version 2.1 385December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1386
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
Nucleus PLUS Internals Manual, Software Version 2.1 387December 15, 2006
Release Macros Error FunctionsThe following sections provide a brief description of the macros in the RL.
Nucleus PLUS Internals Manual, Software Version 2.1388
Component DescriptionsPLUS_RELEASE_STRING
December 15, 2006
PLUS_RELEASE_STRINGDescription
This macro returns the Nucleus PLUS release string.
Nucleus PLUS Internals Manual, Software Version 2.1 389December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1390
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
Nucleus PLUS Internals Manual, Software Version 2.1 391December 15, 2006
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:
Nucleus PLUS Internals Manual, Software Version 2.1392
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
Nucleus PLUS Internals Manual, Software Version 2.1 393December 15, 2006
• 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
Nucleus PLUS Internals Manual, Software Version 2.1394
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.
ESAL ComponentComponent Functional Areas
Nucleus PLUS Internals Manual, Software Version 2.1 395December 15, 2006
Figure 5-5. ESAL Component Functional Areas
Nucleus PLUS Internals Manual, Software Version 2.1396
ESAL ComponentComponent 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)
Nucleus PLUS Internals Manual, Software Version 2.1 397December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1398
ESAL ComponentGeneric Component (GE)
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
ESAL ComponentGeneric Component (GE)
Nucleus PLUS Internals Manual, Software Version 2.1 399December 15, 2006
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).
Nucleus PLUS Internals Manual, Software Version 2.1400
ESAL ComponentGeneric Component (GE)
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.
ESAL ComponentGeneric Component (GE)
Nucleus PLUS Internals Manual, Software Version 2.1 401December 15, 2006
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)
Nucleus PLUS Internals Manual, Software Version 2.1402
ESAL ComponentGeneric Component (GE)
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
Nucleus PLUS Internals Manual, Software Version 2.1 403December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1404
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
Nucleus PLUS Internals Manual, Software Version 2.1 405December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1406
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
Nucleus PLUS Internals Manual, Software Version 2.1 407December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1408
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
Nucleus PLUS Internals Manual, Software Version 2.1 409December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1410
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
Nucleus PLUS Internals Manual, Software Version 2.1 411December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1412
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
Nucleus PLUS Internals Manual, Software Version 2.1 413December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1414
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
Nucleus PLUS Internals Manual, Software Version 2.1 415December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1416
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
Nucleus PLUS Internals Manual, Software Version 2.1 417December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1418
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
Nucleus PLUS Internals Manual, Software Version 2.1 419December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1420
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
Nucleus PLUS Internals Manual, Software Version 2.1 421December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1422
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
Nucleus PLUS Internals Manual, Software Version 2.1 423December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1424
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
Nucleus PLUS Internals Manual, Software Version 2.1 425December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1426
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.
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_Remaining_Size_Get
Nucleus PLUS Internals Manual, Software Version 2.1 427December 15, 2006
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.
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
Functions Called
ESAL_GE_MEM_Region_Addr_Search
Nucleus PLUS Internals Manual, Software Version 2.1428
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
Nucleus PLUS Internals Manual, Software Version 2.1 429December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1430
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
Nucleus PLUS Internals Manual, Software Version 2.1 431December 15, 2006
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).
Nucleus PLUS Internals Manual, Software Version 2.1432
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
Nucleus PLUS Internals Manual, Software Version 2.1 433December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1434
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_GE_ISR_HANDLER_SET
ESAL ComponentESAL_GE_TMR_OS_Timer_Start
Nucleus PLUS Internals Manual, Software Version 2.1 435December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1436
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)
Nucleus PLUS Internals Manual, Software Version 2.1 437December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1438
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
Nucleus PLUS Internals Manual, Software Version 2.1 439December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1440
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
Nucleus PLUS Internals Manual, Software Version 2.1 441December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1442
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
Nucleus PLUS Internals Manual, Software Version 2.1 443December 15, 2006
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>.
Nucleus PLUS Internals Manual, Software Version 2.1444
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
Nucleus PLUS Internals Manual, Software Version 2.1 445December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1446
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.
ESAL ComponentArchitecture Specific Component (AR)
Nucleus PLUS Internals Manual, Software Version 2.1 447December 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 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
Nucleus PLUS Internals Manual, Software Version 2.1448
ESAL ComponentArchitecture Specific Component (AR)
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
Nucleus PLUS Internals Manual, Software Version 2.1 449December 15, 2006
ESAL_AR_DBG_InitializeUsage
VOID ESAL_AR_DBG_Initialize(VOID)
Description
This function initializes debugging at the architecture level.
This function performs the following steps:
• 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
Nucleus PLUS Internals Manual, Software Version 2.1450
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.
This function performs the following steps:
• 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
Nucleus PLUS Internals Manual, Software Version 2.1 451December 15, 2006
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.
This function performs the following steps:
• 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
Nucleus PLUS Internals Manual, Software Version 2.1452
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.
This function performs the following steps:
• 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_GE_MEM_READ16]
ESAL ComponentESAL_AR_DBG_Opcode_Write
Nucleus PLUS Internals Manual, Software Version 2.1 453December 15, 2006
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.
This function performs the following steps:
• Tests if executing in Normal or Thumb mode
• 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]
Nucleus PLUS Internals Manual, Software Version 2.1454
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).
This function performs the following steps:
• Tests if executing in Normal or Thumb mode
• Returns the Normal or Thumb mode Breakpoint opcode.
Functions Called
None.
ESAL ComponentESAL_AR_DBG_Step_Addr_Get
Nucleus PLUS Internals Manual, Software Version 2.1 455December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1456
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
Nucleus PLUS Internals Manual, Software Version 2.1 457December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1458
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_GE_MEM_READ16]
[ESAL_GE_MEM_READ32]
[ESAL_AR_DBG_Orig_Brk_Handler]
ESAL ComponentESAL_AR_DBG_Brk_Exit
Nucleus PLUS Internals Manual, Software Version 2.1 459December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1460
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
Nucleus PLUS Internals Manual, Software Version 2.1 461December 15, 2006
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]
Nucleus PLUS Internals Manual, Software Version 2.1462
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
Nucleus PLUS Internals Manual, Software Version 2.1 463December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1464
ESAL ComponentESAL_AR_ISR_<Interrupt_Type>_Handler
December 15, 2006
• Return to the point of the interrupt
Due to architectural and performance requirements, this function is normally written as anassembly language function.
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
Nucleus PLUS Internals Manual, Software Version 2.1 465December 15, 2006
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
Due to architectural and performance requirements, this function is normally written as anassembly language function.
Functions Called
Architecture Specific
Nucleus PLUS Internals Manual, Software Version 2.1466
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
Nucleus PLUS Internals Manual, Software Version 2.1 467December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1468
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
Nucleus PLUS Internals Manual, Software Version 2.1 469December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1470
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
Nucleus PLUS Internals Manual, Software Version 2.1 471December 15, 2006
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>.
Nucleus PLUS Internals Manual, Software Version 2.1472
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
Nucleus PLUS Internals Manual, Software Version 2.1 473December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1474
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
Nucleus PLUS Internals Manual, Software Version 2.1 475December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1476
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).
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_ICACHE_ALL_INVALIDATE
Nucleus PLUS Internals Manual, Software Version 2.1 477December 15, 2006
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).
This function is included only if the conditional below, contained in esal_co_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_CO_CACHE_AVAILABLE
Nucleus PLUS Internals Manual, Software Version 2.1478
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).
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_ICACHE_INVALIDATE
Nucleus PLUS Internals Manual, Software Version 2.1 479December 15, 2006
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 is included only if the conditional below, contained in esal_co_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_CO_CACHE_AVAILABLE
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.
Nucleus PLUS Internals Manual, Software Version 2.1480
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 is included only if the conditional below, contained in esal_co_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_CO_CACHE_AVAILABLE
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
Nucleus PLUS Internals Manual, Software Version 2.1 481December 15, 2006
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 is included only if the conditional below, contained in esal_co_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_CO_CACHE_AVAILABLE
This function only applies to writeback / copyback cache regions. If writeback/copyback cacheis not available for a specific core, this macro will do nothing.
Nucleus PLUS Internals Manual, Software Version 2.1482
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 is included only if the conditional below, contained in esal_co_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_CO_CACHE_AVAILABLE
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)
Nucleus PLUS Internals Manual, Software Version 2.1 483December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1484
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
Nucleus PLUS Internals Manual, Software Version 2.1 485December 15, 2006
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).
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_PR_INTERRUPTS_AVAILABLE
Functions Called
Processor specific
Nucleus PLUS Internals Manual, Software Version 2.1486
ESAL ComponentESAL_PR_INT_Disable
December 15, 2006
ESAL_PR_INT_DisableUsage
VOID ESAL_AR_INT_Disable (INT vector_id)
Description
This function disables the given interrupt source
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_ISR_<Interrupt_Type>_Handler
Nucleus PLUS Internals Manual, Software Version 2.1 487December 15, 2006
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
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_PR_INTERRUPTS_AVAILABLE
Functions Called
ESAL_GE_ISR_HANDLER_EXECUTE
Nucleus PLUS Internals Manual, Software Version 2.1488
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.
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_PR_INTERRUPTS_AVAILABLE
Functions Called
ESAL_GE_ISR_HANDLER_SET
ESAL ComponentESAL_PR_MEM_Cache_Enable
Nucleus PLUS Internals Manual, Software Version 2.1 489December 15, 2006
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.
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_PR_CACHE_AVAILABLE
Nucleus PLUS Internals Manual, Software Version 2.1490
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).
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
ESAL ComponentESAL_PR_MEM_ICACHE_ALL_INVALIDATE
Nucleus PLUS Internals Manual, Software Version 2.1 491December 15, 2006
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).
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
Nucleus PLUS Internals Manual, Software Version 2.1492
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).
This function is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
ESAL ComponentESAL_PR_MEM_ICACHE_INVALIDATE
Nucleus PLUS Internals Manual, Software Version 2.1 493December 15, 2006
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 is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
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.
Nucleus PLUS Internals Manual, Software Version 2.1494
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 is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
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
Nucleus PLUS Internals Manual, Software Version 2.1 495December 15, 2006
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 is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
This function only applies to writeback / copyback cache regions. If writeback / copybackcache is not available for a specific processor, this macro will do nothing.
Nucleus PLUS Internals Manual, Software Version 2.1496
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 is included only if the conditional below, contained in esal_pr_cfg.h, is defined asESAL_TRUE.
ESAL_ESAL_PR_CACHE_AVAILABLE
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
Nucleus PLUS Internals Manual, Software Version 2.1 497December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1498
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)
Nucleus PLUS Internals Manual, Software Version 2.1 499December 15, 2006
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.
Nucleus PLUS Internals Manual, Software Version 2.1500
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
Nucleus PLUS Internals Manual, Software Version 2.1 501December 15, 2006
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
Nucleus PLUS Internals Manual, Software Version 2.1502
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
Nucleus PLUS Internals Manual, Software Version 2.1 503December 15, 2006
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.
ESAL_DP_INTERRUPTS_AVAILABLE
Functions Called
Development Platform specific
Nucleus PLUS Internals Manual, Software Version 2.1504
ESAL ComponentESAL_DP_INT_Disable
December 15, 2006
ESAL_DP_INT_DisableUsage
VOID ESAL_DP_INT_Disable (INT vector_id)
Description
This function disables the given interrupt source
This function is included only if the following conditional, contained in esal_dp_cfg.h, isdefined as ESAL_TRUE.
ESAL_DP_INTERRUPTS_AVAILABLE
ESAL ComponentESAL_DP_ISR_<Interrupt_Type>_Handler
Nucleus PLUS Internals Manual, Software Version 2.1 505December 15, 2006
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
This function is included only if the following conditional, contained in esal_dp_cfg.h, isdefined as ESAL_TRUE.
ESAL_DP_INTERRUPTS_AVAILABLE
Functions Called
ESAL_GE_ISR_HANDLER_EXECUTE
Nucleus PLUS Internals Manual, Software Version 2.1506
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.
ESAL_DP_INTERRUPTS_AVAILABLE
Functions Called
ESAL_GE_ISR_HANDLER_SET
Summary Flow ChartsThe following flow charts summarize the ESAL initialization (reset), and low-level interruptsequence.
ESAL ComponentSummary Flow Charts
Nucleus PLUS Internals Manual, Software Version 2.1 507December 15, 2006
Figure 5-8. ESAL Initialization (Reset) Sequence
Nucleus PLUS Internals Manual, Software Version 2.1508
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.
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