SPARCompiler Ada Runtime System Guide

336 Pages·1999·0.5 MB·English

SPARCompiler Ada Runtime System Guide
A Sun Microsystems, Inc. Business
2550 Garcia Avenue
Mountain View, CA 94043
U.S.A.
Part No.: 801-4864-11
Revision B, August 1994
(cid:211) 1994 Sun Microsystems, Inc.
2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A.
All rights reserved. This product and related documentation are protected by copyright and distributed under licenses
restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be
reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.
Portions of this product may be derived from the UNIX® and Berkeley 4.3 BSD systems, licensed from UNIX System
Laboratories, Inc., a wholly owned subsidiary of Novell, Inc., and the University of California, respectively. Third-party font
software in this product is protected by copyright and licensed from Sun’s font suppliers.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions
set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.
The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.
TRADEMARKS
Sun, the Sun logo, Sun Microsystems, Sun Microsystems Computer Corporation, Solaris, are trademarks or registered
trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark of Novell, Inc., in
the United States and other countries; X/Open Company, Ltd., is the exclusive licensor of such trademark. OPEN LOOK® is a
registered trademark of Novell, Inc. PostScript and Display PostScript are trademarks of Adobe Systems, Inc. All other
product names mentioned herein are the trademarks of their respective owners.
All SPARC trademarks, including the SCD Compliant Logo, are trademarks or registered trademarks of SPARC International,
Inc. SPARCstation, SPARCserver, SPARCengine, SPARCstorage, SPARCware, SPARCcenter, SPARCclassic, SPARCcluster,
SPARCdesign, SPARC811, SPARCprinter, UltraSPARC, microSPARC, SPARCworks, and SPARCompiler are licensed
exclusively to Sun Microsystems, Inc. Products bearing SPARC trademarks are based upon an architecture developed by Sun
Microsystems, Inc.
VADS, VADScross, and Verdix are registered trademarks of Rational Software Corporation (formerly Verdix).
The OPEN LOOK and Sun™ Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees.
Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user
interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface,
which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license
agreements.
X Window System is a product of the Massachusetts Institute of Technology.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE
PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW
EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN
THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.
Please
Recycle
Contents
1. Runtime System Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
1.2 The SCAda Runtime Structure . . . . . . . . . . . . . . . . . . . 1-2
1.2.1 The Ada Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
1.2.2 Ada Tasking and VADS Extensions. . . . . . . . . . . 1-3
1.3 How the VADS Threaded Runtime Works. . . . . . . . . . 1-4
1.4 Debugging and the Runtime System. . . . . . . . . . . . . . . 1-5
1.5 VADS Threaded vs. Solaris MT Runtime . . . . . . . . . . . 1-5
1.5.1 Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.5.2 Multithreaded Ada. . . . . . . . . . . . . . . . . . . . . . . . . 1-6
1.5.3 When to Use the VADS Threaded Runtime. . . . . 1-7
1.5.4 Parallel Programming is Tricky. . . . . . . . . . . . . . . 1-7
1.6 Runtime System Interfaces . . . . . . . . . . . . . . . . . . . . . . . 1-8
1.6.1 ada_krn_defs.a andada_krn_i.a . . . . . . . . 1-10
2. Runtime System Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
iii
2.1 Ada Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
2.1.1 Ada Kernel Implementation. . . . . . . . . . . . . . . . . 2-3
2.2 Passive Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41
2.2.1 Pragma passive . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41
2.2.2 Passive Task Portability . . . . . . . . . . . . . . . . . . . . . 2-45
2.2.3 Passive Task Restrictions . . . . . . . . . . . . . . . . . . . . 2-46
2.2.4 Compiler Error Messages for Passive Tasks . . . . 2-48
2.2.5 Examples of Passive Tasks Errors. . . . . . . . . . . . . 2-49
2.2.6 Ada Interrupt Entries as Interrupt Handlers. . . . 2-51
2.3 When a Program Exits or Deadlocks . . . . . . . . . . . . . . . 2-55
2.4 SCAda Archive Interface Packages. . . . . . . . . . . . . . . . 2-56
2.5 Tasking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-57
2.5.1 Task Creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-59
2.5.2 Task Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-61
2.5.3 Task Start-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63
2.5.4 Delay Statements. . . . . . . . . . . . . . . . . . . . . . . . . . 2-64
2.5.5 Task Entry Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-65
2.5.6 Accept andSelect Statements . . . . . . . . . . . . . 2-67
2.5.7 Task Completion and Termination . . . . . . . . . . . . 2-69
2.6 Fast Rendezvous Optimization. . . . . . . . . . . . . . . . . . . . 2-70
3. Memory Management and Allocation. . . . . . . . . . . . . . . . . . 3-1
3.1 Memory Management/Requirements Implementation 3-1
3.1.1 Explicit Memory Requirements. . . . . . . . . . . . . . . 3-2
3.1.2 Implicit Memory Requirements . . . . . . . . . . . . . . 3-3
iv SPARCompiler Ada Runtime System Guide
3.1.3 Heap Management . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
3.1.4 Stack Management . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.2 Memory Allocation Support in the SCAda Runtime
System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
3.3 Allocators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
3.4 SCAda Library Memory Management Semantics. . . . 3-10
3.4.1 AA_GLOBAL_NEW . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
3.4.2 AA_ALIGNED_NEW . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
3.4.3 AA_GLOBAL_FREE . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
3.4.4 AA_LOCAL_NEW. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
3.4.5 AA_LOCAL_FREE . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
3.4.6 EXTEND_INTR_HEAP. . . . . . . . . . . . . . . . . . . . . . . 3-15
3.4.7 GET_INTR_HEAP_SIZE. . . . . . . . . . . . . . . . . . . . . 3-15
3.4.8 KRN_AA_GLOBAL_NEW andKRN_AA_GLOBAL_
FREE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
3.4.9 EXTEND_STACK. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
3.4.10 AA_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
3.5 SCAdasupplied Memory Management . . . . . . . . . . . . 3-16
3.5.1 Simple Allocation:SMPL_ALLOC . . . . . . . . . . . . . 3-16
3.5.2 Slim Heap Allocation:SLIM_MALLOC . . . . . . . . . 3-17
3.5.3 Fat Heap Allocation:FAT_MALLOC . . . . . . . . . . . 3-21
3.5.4 Small Block Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
3.5.5 Allocation from Interrupt Handlers. . . . . . . . . . . 3-23
3.5.6 Debug Heap Allocation:DBG_MALLOC . . . . . . . . 3-26
3.5.7 Configuring in a Non-default Allocation Archive 3-29
Contents v
3.5.8 pragmaRTS_INTERFACE. . . . . . . . . . . . . . . . . . . 3-30
3.5.9 Pool-based Allocation:POOL. . . . . . . . . . . . . . . . . 3-31
3.5.10 Pool Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
3.5.11 Suggestions for Use of SCAda Memory Allocation 3-37
3.5.12 Mutual Exclusion During Allocation . . . . . . . . . . 3-38
3.5.13 Memory Management and Underlying Operating
Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
3.5.14 Protected Malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40
3.5.15 Replacing User-space Memory Allocation. . . . . . 3-40
3.5.16 Memory Allocation Exerciser . . . . . . . . . . . . . . . . 3-41
4. Ada Runtime Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
4.1 Overview and Interface Description . . . . . . . . . . . . . . . 4-2
packageV_INTERRUPTS — provides interrupt processing 4-7
procedure/function ATTACH_ISR — attach ISR to interrupt
vector and optionally return the previously attached
ISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13
functionCURRENT_INTERRUPT_STATUS — returns
mask/priority setting. . . . . . . . . . . . . . . . . . . . . . . 4-15
functionCURRENT_SUPERVISOR_STATE — returns
supervisor/user state of task. . . . . . . . . . . . . . . . . 4-16
function/procedure DETACH_ISR — detach an ISR from an
interrupt vector and optionally return the previously
attached ISR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
procedureENTER_SUPERVISOR_STATE — enter a task
supervisor state. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
genericprocedureFAST_ISR — a faster version of the ISR
generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
vi SPARCompiler Ada Runtime System Guide
genericprocedureFLOAT_WRAPPER —
save/restore floating-point coprocessor state. . . 4-20
genericprocedureISR — entry and exit code for ISRs 4-21
procedureLEAVE_SUPERVISOR_STATE — exit a task
supervisor state. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
functionSET_INTERRUPT_STATUS — change the mask or
priority setting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
function SET_SUPERVISOR_STATE — change
supervisor/user state of task. . . . . . . . . . . . . . . . . 4-24
packageV_MAILBOXES — provides mailbox operations 4-25
function/procedureCREATE_MAILBOX —
create a mailbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31
functionCURRENT_MESSAGE_COUNT — returns number
unread messages. . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33
procedureDELETE_MAILBOX — remove a mailbox. . . . 4-34
procedureREAD_MAILBOX — retrieve a message . . . . . 4-36
procedureWRITE_MAILBOX — deposit a message. . . . . 4-38
packageV_MEMORY — provides memory management
operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40
procedureCREATE_FIXED_POOL — create aFixedPool. 4-46
procedureCREATE_FLEX_POOL — create aFlexPool. . . 4-47
procedureCREATE_HEAP_POOL — create aHeapPool . . 4-48
procedureDESTROY_FIXED_POOL — delete aFixedPool 4-49
procedureDESTROY_FLEX_POOL — delete aFlexPool . 4-50
procedureDESTROY_HEAP_POOL — delete aHeapPool. 4-51
genericfunctionFIXED_OBJECT_ALLOCATION — allocate
FixedPool object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52
Contents vii
genericprocedureFIXED_OBJECT_DEALLOCATION —
deallocateFixedPool memory. . . . . . . . . . . . . . . . . 4-53
genericfunctionFLEX_OBJECT_ALLOCATION — allocate a
FlexPool object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54
genericprocedureFLEX_OBJECT_DEALLOCATION —
deallocateFlexPool memory. . . . . . . . . . . . . . . . . . 4-55
genericfunctionHEAP_OBJECT_ALLOCATION — allocate
HeapPool object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-56
procedureINITIALIZE_SERVICES — initialize memory
services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57
packageV_SEMAPHORES — provides binary and counting
semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-59
procedureCREATE_SEMAPHORE — create a semaphore 4-64
procedureDELETE_SEMAPHORE — delete a semaphore 4-67
procedureSIGNAL_SEMAPHORE — perform a signal
operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69
procedureWAIT_SEMAPHORE — perform a wait operation 4-70
packageV_STACK — provides stack operations . . . . . . . 4-72
procedureCHECK_STACK — returns stack pointer value and
lower limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-73
procedureEXTEND_STACK — extends the current stack 4-74
packageV_XTASKING — provides Ada task operations. 4-75
functionALLOCATE_TASK_STORAGE — allocates storage in the
task control block . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84
functionCALLABLE — returns the value of a taskP’CALLABLE
attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85
functionCURRENT_EXIT_DISABLED — returns current value
for kernelEXIT_DISABLED_FLAG. . . . . . . . . . . . 4-86
viii SPARCompiler Ada Runtime System Guide
function CURRENT_FAST_RENDEZVOUS_ENABLED — return
value ofFAST_RENDEZVOUS_ENABLED flag . . . 4-87
function CURRENT_PRIORITY — returns the priority of a
task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-88
functionCURRENT_PROGRAM — returns the current program
identifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89
functionCURRENT_TASK — returns the current task
identifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-90
functionCURRENT_TIME_SLICE — returns current time slice
interval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-91
functionCURRENT_TIME_SLICING_ENABLED —
checks if time slicing is enabled . . . . . . . . . . . . . . 4-92
functionCURRENT_USER_FIELD — returns value of user-
modifiable field. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-93
procedureDISABLE_PREEMPTION —
inhibits the current task from being preempted . 4-94
procedureDISABLE_TASK_COMPLETE - disables completion
and termination of task . . . . . . . . . . . . . . . . . . . . . 4-95
procedureENABLE_PREEMPTION — allows the current task to
be preempted. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96
procedureENABLE_TASK_COMPLETE —
enables completion and termination of task . . . . 4-97
functionGET_PROGRAM — returns a task program
identifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-98
functionGET_PROGRAM_KEY — returns the user-defined key
for the program. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-99
functionGET_TASK_STORAGE — returns starting address of
task storage area . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-100
function GET_TASK_STORAGE2 — get task storage using OS's
ID of task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-101
Contents ix
functionID — returns a task identifier . . . . . . . . . . . . . . 4-102
procedureINSTALL_CALLOUT —
installs a procedure to call at a program, task, or idle
event. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-104
function OS_ID — return the underlying OS task or program
identifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-107
procedureRESUME_TASK — resume execution of a task 4-108
procedureSET_EXIT_DISABLED — change the kernel
EXIT_DISABLED_FLAG. . . . . . . . . . . . . . . . . . . . . 4-110
procedure SET_FAST_RENDEZVOUS_ENABLED — set
FAST_RENDEZVOUS_ENABLED flag. . . . . . . . . . . 4-111
procedureSET_PRIORITY — change a task priority. . . 4-112
procedureSET_TIME_SLICE — change a task time slice
interval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-113
procedureSET_TIME_SLICING_ENABLED — enable or disable
time slicing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-114
procedureSET_USER_FIELD — change a task user-modifiable
field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-115
functionSTART_PROGRAM — start a separately-linked
program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-116
procedureSUSPEND_TASK — suspend execution of task 4-118
functionTERMINATED — returns value ofP’TERMINATED
attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-119
procedureTERMINATE_PROGRAM — terminates the specified
program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-120
genericfunctionV_ID — returns the identifier for a task of a
specified type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-121
A. A Summary of RTS Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
A.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1
x SPARCompiler Ada Runtime System Guide