This release note applies to Release 4.0.0 B of Rational Apex Ada 95/83 for LynxOS. Full instructions for using this product are provided in Programming for LynxOS.

This document contains only release notes specific to LynxOS cross-development. Release notes for the parts of this product that are also applicable to the native Apex product are provided in the Rational Apex Release Note.

Note: Starting with the 4.0.0 releases, the rada executable used to code Apex Embedded Ada views is the same executable shipped with the native product (Please check the native Apex patch descriptions for possible newer versions of rada).

The "latest" Release Notes for LynxOS can be viewed on–line.

• Host and Target Specifications
• Documentation
• New Features in Release 4.0.0B
• Introduction to Cross-Development for LynxOS
• Special Considerations
• Installation Requirements
• Installing the LynxOS Cross Development System
• Installation For C/C++
• Installation For AXI Bindings
• Known Limitations
• Defects Resolved

Host: Sun SPARC workstations running Solaris 2.6, Solaris 7, or Solaris 8.

Target: LynxOS 3.1.0, PowerPC CPU with patch set 010.

Documents specific to this product are:

Embedded Programming Guide for LynxOS
Release Note for LynxOS (this document)
Command Reference
Utilities Guide

These documents are available in online format. They can be accessed through the Help > Manuals command. Postscript versions of the documents can be printed using the Help > Print Manuals command.

Starting with the 4.0.0 releases, the rada executable used to code Apex Embedded Ada views is the same executable shipped with the native product (Please check the native Apex patch descriptions for possible newer versions of rada). The code generator apex_ada_cg_phase and optimizer apex_ada_optim_phase executables are not shared. The location of the rada, apex_ada_cg_phase and apex_ada_optim_phase executables are determined from the view the user is coding in. The apex_compiler_tool script can be used to determine the location of these tools. For example:

% apex_compiler_tool -show_tools
/tools/rational/releases/apex.4.0.0b/sun4_solaris2/bin/rada
/tools/rational/releases/apex_embedded.4.0/bin/power/lx/apex_ada_cg_phase
/tools/rational/releases/apex_embedded.4.0/bin/power/lx/apex_ada_optim_phase

Apex Embedded provides many $APEX_BASE/ada/model.ss views with each release. The view names can be long and their meaning can be obscure. To help make sense of the information encoded in the view name, each model is now shipped with a description file. The description files explain what the cryptic portions of the view name mean.

This description can be viewed from the command line by invoking the properties command with the -model_info option. The properties command can specify a model.ss view directly, or another view modeled on a model.ss view.

The description can also be viewed from the GUI. Dialogs that ask the user to select a model (e.g. File > New > New View) have a navigation icon next to the text field. Clicking the navigation icon displays the Model Navigator dialog. Once a specific model has been selected within the Model Navigator dialog, the model description file will be displayed in the "Information on selected model" section.

The following four dialogs have been combined into a single dialog.

• File > Run
• File > Debug
• File > Download
• Tools > Targets

Each function is still accessed via the menus above. Once the dialog appears, users can switch between the four functions by selecting tabs within the dialog.

The Control > Maintenance > Upgrade To New Release dialog and corresponding apex_upgrade script are part of the Apex Native product. Starting with the 4.0.0B Native Apex release, this dialog and script now work for Apex Embedded.

Users can now link, run, and debug programs from within Clearcase.

Customers can purchase source releases of Apex Embedded products. These source releases include full source to $APEX_BASE/ada/*.ss/*.rel views (no API's) including the views used to create the runtime archives.

The File > New > New Source Release dialog can be used to make a copy of the entire set of views so that development work will not alter the installed product.

When doing development that effects the runtime archives, it can be difficult to determine what views need recoding, and what runtimes need re-linking after source code changes have been made. To simplify this process, we have created the apex_create_libraries command. The syntax of this command is simple. You point it at the directory containing links to all the runtimes archives (i.e. the directory identified by a model's RUNTIMES switch) and it takes care of coding views, and re-linking archives.

The default alignment of types and objects has changed in Apex 4.0.0. Be aware that in the absence of representation clauses specifying the alignment of a type or object, the compiler is free to choose the optimal alignment with respect to performance. See the Apex native Release Notes for more details.

The Ada Runtime for Apex 4.0.0 has been migrated to POSIX 1.c under LynxOS 3.1.0.

The Rational Apex 3.2.0 Embedded Solaris to PowerPC for LynxOS product supports LynxOS 3.0.1. This version of LynxOS does not support the POSIX_THREAD_PRIO_PROTECT mutex locking protocol. As a result, Apex 3.2.0 implements protected objects compiled with pragma Locking_Policy (Ceiling_Locking) with a combination of PTHREAD_PRIO_NONE mutexes, which have no effect on thread (and therefore task) priority, and explicit priority change using pthread_setschedparam(). This is not fully compliant with the Ada real-time scheduling as specified by pragma Task_Dispatching_Policy (Fifo_Within_Priority), since explicit priority changes move the thread to the back of the scheduling queue for its priority, where loss of ceiling priority should leave it at the front of the queue. The result is that a task incorrectly yields the processor to other tasks of the same priority when completing a protected action.

The corresponding Apex 4.0.0B product supports LynxOS 3.1.0a which does support POSIX_THREAD_PRIO_PROTECT mutexes. The Apex 4.0.0 runtime for LynxOS has been modified to use these mutexes, eliminating explicit priority changes when completing a protected action. Loss of ceiling priority when unlocking a mutex using this policy leaves the thread at the head of the queue for its priority, as required by the Ada Fifo_Within_Priorities scheduling policy.

Ada.Asynchronous_Task_Control, previously found in views in the Real_Time_Systems subsystem has been removed because it cannot be fully supported on a LynxOS target.

Apex 3.0.1 for embedded platforms included the package Language in the rational.ss subsystem. This package provides constants useful for interfacing to other language implementations on those platforms. For example, the prefix character added to link names by those language implementations.

The function of this package has been superseded by the Apex implementation of the Import, Export, Convention, and Calling_Convention pragmas. In particular, the compiler will treat the External_Name argument to the Import and Export pragmas as a name in the target language and perform the necessary modifications to that name to create the corresponding link name. Note that no modifications are made if the Link_Name parameter is used instead of External_Name.

These features make the Language package obsolete for the Apex embedded products. It has therefore been removed from 3.2.0 and later embedded releases.

In embedded VADS programs Ada address clauses for with static addresses were represented by a linker group to prevent overlapping use of the memory associated with address clause variables. This feature is no longer supported by the Apex compiler. The Apex compiler allocates a pointer to the address specified in the address clause and all accesses to the variable are implemented as indirect references through this pointer.

In some circumstances the optimizer is able to optimize away the pointer and make references directly to the specified address. There is no mechanism to assure that the specified memory address isn't allocated by the linker to some other part of the user program.

For a complete description of the following commands see the Programmer's Guide.

apex_execute

The new version of apex_execute differs as follows:

• It has a -help option.
• It can take a -logical_target parameter (though if this parameter is not specified, the LOGICAL_TARGET_NAME switch for the enclosing view).
• It is written in apex shell, not cshell.

apex_simulator

The new version of apex_simulator differs as follows:

• has a -help option.
• is written in apex shell, not cshell.
• has a -sim_file option which allows you to override the default selection.
• has a -logical option which allows you to map the simulator to a logical target as part of the apex_simulator command.

apex_add_target and apex_target_control have been replaced with the new commands mentioned above.

The following debugger enhancements are now available:

• Target initiated debugger connection simplifies target configuration (removes the gdbserver port field in the target dialogs).
• Program Input/output that is identical to the rest of the Apex embedded product line.
• Asynchronous attach to a running program.
• Less intrusive debugging of tasking applications due to less interaction between the target and the debugger during normal operation.
• Serial debugging.
• Proxy debugging.

Attaching task entries to interrupts has been made operational on all architectures.

The LynxOS debugger can now attach onto a running process.

To use this feature you must first obtain the thread id of the running process. Logon to your LynxOS target and execute the following command.

> px xat

Now from the debugger dialog, specify the tid of your thread in the attach field provided.

You can also run the debugger from the command-line

$ apex_debug -a 15 hello

The runtime for LynxOS is internally compatible with the other pthreads implementations. Although not user visible, this internal sharing provides a more reliable implementation of LynxOS with many bug fixes that have been leveraged from the other pthread environments (Solaris, HP, SGI, OSF, and AIX)

All of the runtime archive and predefined components have been compiled at optimization level 2 with the optimization objective set to space (instead of time). This provides the smallest footprint for embedded applications as well as the best performance.

Target Control has been restructured for the 3.2.0B release. New target control gui implementation allows physical targets to be globally visible resources for a development team yet still allow individuals to reserve individual physical targets. Multiple targets can be manipulated from the same Apex session.

Please read the Target Control Chapter in the Programming Guide and refer to Getting Started.

ACVC validation test suites are certified at optimization levels 0, 1 and 2 with optimization objective of SPACE.

With Apex, cross-development for a LynxOS target is almost identical to native Apex development. The primary difference is that the resulting executable code runs on a target machine which is different than the development machine.

The same Apex user interface is used for both native and cross development. Thus, editing, navigation, compiling, and even linking proceed using the same key and mouse sequences.

In order to run the target program, it must be copied to the target machine and executed there. Fortunately, Apex automates these steps, so the run and debug commands operate in virtually the same manner as they do for native development. Internally, of course, the commands perform additional steps.

When running your executable, Apex opens two xterms: one shows the progress of the steps required for execution, and the second logs in to the target. When the program has completed, you must enter Exit on the target xterm. You can then close the first xterm by entering Control-C.

---

Special Considerations

There are some special considerations for LynxOS cross-development. These considerations arise from the fact that developing for LynxOS is cross-development, but the target is a full-featured OS with most UNIX features, rather than a processor board. LynxOS development shares characteristics of native and cross development.

1 . When running Apex tools, especially the debugger, remember that while the tool runs on the host, the resulting executable program runs on a different machine.

The most obvious instance of this is standard input and output. When using the debugger, the program actually writes its output on the target.

2 . Similarly, with LynxOS, the file system is on the target. For example, if your program opens and writes to a file named temp.tmp, the file is on the target.

For native development, the host is the same as the target, so the file ends up on the host system itself. For most versions of Apex cross, the target is a separate machine but the file system is simulated on the host. (This feature makes it easier to develop test software or diagnostic tools.) In either case, if you are used to developing with Apex, you may be used to having file I/O end up on the host system.

3 . The final link step uses the LynxOS cross-linker.

A third-party linker is invoked for LynxOS cross development. This technique allows the Apex user to use the target linker developed by the vendor and thereby maximize the compatibility with third-party and OS-specific libraries which are typically targeted to that linker. This is different from most Apex crosses, where Rational supplies an embedded linker.

The downside of this strategy is that some third-party linkers are not very helpful in diagnosing link-time problems. The Lynx cross-linker is no exception. Apex is able to diagnose problems only through the prelinking phase. The tools $APEX_LYNX_ROOT/usr/bin/nm and objdump are especially helpful in diagnosing link problems.

4 . Apex uses rcp to copy the executable to the LynxOS target. Thus, each developer must have a login on this target, along with rcp privileges.

5 . Apex logs onto your target machine using expect. This tool assumes that your login prompt on the target is "% ". If it does not recognize your prompt, run and debug will probably work, but with long delays. Setting your prompt to end in "% " will avoid delays.

To develop code for a LynxOS target, you must have the following installed. Specific versions for these can be found in Host and Target Specifications

• Apex Ada 95/83 Sun SPARC Solaris.
• Apex Ada 95/83, Sun SPARC Solaris to LynxOS PowerPC (this product). This product is installed as an add-on to the native product.
• LynxOS Cross Development System for Sun SPARC Solaris, PowerPC target.

• LynxOS.

In order to debug programs running under LynxOS, a special debug daemon must first be downloaded to your Lynx target. This daemon is called gdbserver.

The blueprint for copying gdbserver to your Lynx target is:

% apex_load_gdbserver LYNX_TARGET:REMOTE_SERVER_LOC/gdbserver

Replace LYNX_TARGET with the name (or IP address) of your Lynx target. Replace REMOTE_SERVER_LOC with a fully rooted path to the existing directory where you want to put the gdbserver. Then execute the command from an Apex shell.

Instructions for installing Apex tools are provided in the Installation Guide.

When Apex for LynxOS is installed, the value for the environment variable $APEX_LYNX_ROOT is defined. Apex uses this variable to find components of the LynxOS Cross Development System. On LynxOS3.0.0, the usual value for $APEX_LYNX_ROOT is:

/usr/lynx/3.0.0/ppc/cdk/sunos-xcoff-ppc

There is one additional step specific to LynxOS development which must be completed. This step is the installation of the LynxOS Cross Development System. Apex uses its linker and the LynxOS system libraries.

Follow the instructions in the LynxOS documentation for doing this.

Remember that you are installing this on the Solaris host, not the LynxOS target. The Solaris host is the machine that the Lynx Guide calls the "Cross Development Machine." Install for the "ppc" target.

The root for installing the files is /usr/lynx/version/ppc -- the same as $APEX_LYNX_ROOT/../..

Install both the "LynxOS Development Image" (*.devos_tape.tar.gz) and the "Cross Development Image" (*.cdksol1.tar.gz) for SunOS on the host machine.

Apex supports the development of C/C++ code for LynxOS as a separately licensed feature

The optional C/C++ views and tools are selected during the installation dialog. No additional setup is necessary.

AXI Bindings are provided to support development of X-Windows Applications. This is a separately licensed feature.

To install the bindings, select the optional Ada X Interface (AXI) product during the installation dialog.

One additional step is necessary. The LynxOS X11 libraries are required on the host in order to link. These can be copied from the Lynx distribution CD. On the CD, the support files for X-Windows development are found in:

/cdrom/tar_images/*.x11r6_tape.tar.gz
/cdrom/tar_images/*.motif_tape.tar.gz

Expand the tar files (using gunzip or a similar utility) and then use tar to extract the libraries.

% cd /usr/lynx/3.0.1/ppc
% tar xvf x11r6_file\
 usr/lib/libXmu.a  \
 usr/lib/libXext.a \
 usr/lib/libX11.a \
 usr/lib/libXt.a  \
 usr/lib/libSM.a  \
 usr/lib/libICE.a

% tar xvf motif_file\
 usr/lib/libMrm.a   \
 usr/lib/libXm.a    \
 usr/lib/libUil.a

Due to a limitation introduced in LynxOS 3.1.0a, a predefined Ada exception such as Constraint_Error or Program_Error may cause corruption of nonvolatile floating point registers. We anticipate that a future patch to LynxOS will resolve this problem.

Control-C (^C) does not work from within the debugger.

In the Rational Apex 4.0 Embedded Solaris to PowerPC for LynxOS product, for loops may fail to terminate in certain situations. Bcopy, a subprogram internal to the runtime, does not preserve the value of the CTR register, which is used in optimized for loops. Calls to Bcopy are generated by the compiler to copy large objects, e.g. for record or array assignment. If one of these calls is made in the body of an optimized for loop, it may zero CTR, which prevents the loop from terminating.

The circumstances under which this will occur have not been completely characterized. They are rare, and have only been observed at optimization level two. The runtime fix addressing this problem was not available at the time of the release, and will be included in the first patch to this product.

When using File > Debug, output is directed to an xterm. Make sure that you have an xterm executable on your path before starting your Apex session.

When debugging, the Input/Output window is replaced by a new one immediately upon program exit. Put a break at the last line of the program to preserve program output.

(Defect 127507) Running the debugger without first selecting a target under target control causes the debugger to fail. Workaround: Always run Tools > Target Control first.

Problems fixed in the base Apex product are listed in the release notes for the base product.

Refer to your product online documentation, Help > Manuals for the very latest updates to release notes.

Table 1 Defects Resolved in Release 4.0.0B

Defect #	Description
1814	Daylight Saving and Calendar
2859	Check_Config problem
5456	apex_symbol_info is broken for lynx and others?
5462	eTDM fails to init DEC21x4x correctly
5468	Single location for all timer configuration
5554	Comments in v_krn_conf.2.ada are wrong
5607	Floating point register corruption with mixed float types
5630	Link error with pragma Suppress(All_Checks) in separates
5863	Protected object failure
5980	apex_convert fails when relocating Srecords
6066	"The linker option ""Kernel"" is not used in Apex"
6129	LynxOS C++ linking documentation error
6255	"Ada.Real_Time (Time_Unit, Clock, etc.) configuration difficult, incomplete"
6293	Link error when importing C++ routine
6354	Cannot redirect input -- Apex Embedded for LynxOS
6369	System.Default_Bit_Order=High_Order_First for i386; should be Low_Order_First
6552	Internal Error: unable to generate /tmp/embedded_enviroment.10700
6590	disassembly of C objects does not work from the gui
6717	Imports between Ada and C/C++
6861	Lost parameters in a mixed Ada/C++ application
6878	Enabling C++ linking causes a segmentation fault at program termination (Lynx)
7099	Time_Error raised in Split during Daylight Saving Time change

Table 2 Defects Resolved in Release 3.2.0B

Defect	Description	Log Ref.
127133	problem linking cross with testmate/undefined symbols
128134	Float_Random.Reset raises Constraint_Error on PPC simulator	520632
128136	File > Shift-Run does not work in cross views
129089	dialog definition problem when LynxOS and other crosses are installed
129529	Unsupported BAT WIM Bit Settings	523291
129954	task attached to an interrupt via for use at clause generates too much code
129984	Apex->LynxOS attach_handler pragma failure	523747
130970	installing multiple embedded Apex products is confusing and undocumented
131047	Default RAM size (64MB) too large	526246
131552	check_config warning messages are not helpful	527334
132066	Apex unnecessarily generates implicit code	528760
132640	TDM feature, KERNEL_START_ENABLED, not implemented
132710	link_phase: XLINK: Unresolved reference to TS_DEFER_ABORT linking kernel
134067	problem with extend lifetimes and spill code on m68k
140562	elaboration checks randomly generated
140932	v_krn_conf.V_IDLE_PROCESSING should not be visible
141150	Machine_Code for Intel doesn't support MMX & Pentium-II processors
142665	Bad stack level reference for POWER
143011	regression test ar1156a fails: &&& [MID] in Stmt_Gen.Gen_Stmt - CONSTRAINT_E
143018	regression 129799 fails, wants to call System.Time_Interfaces.Normalize_Time
143647	Problems with pragma calling_convention
143837	ACVC chapter c/e fails on repeated tries
143966	Concatenating a null string with a non-null string gives a null string
143997	Lower priority tasks are NOT being preempted by higher priority tasks
144111	Ada 95 Streams Problem with Apexlx 3.0.1
144192	Problem with floating point register save/restore and multi-tasking
144215	Missing files in predefined.ss & numerics.ss
144293	ppc mcode: use of extended word forms causes assertion error in cg
144297	pragma.1.ada ignored when view is not clean
144332	C++ Keys Properties.sw file has errors
144405	Intermittent connection to simulator or ETDM via dbiface/a.run
144528	Constraint_Error raised by gasket when prelinking booch
144723	apex code claims "No objects were coded ..." for the assembler
144757	System.Time_Interfaces is broken
144814	regression 124645 on lynx, extra level of indirection has been lost
145022	bug in rdas, rdemangle, rdb scripts in C++ compiler
145058	Build.scripts need #!/bin/csh -f
145077	problem initialing array of packed records
145083	ada.calendar.split problem
145249	Documentation problem for the Apex Enet configuration
145402	32-bit floats passed in volatile registers
145412	Assembler missing from installation
145567	register offsets in pci_sup package wrong
145568	scan_bus ignores devices whos IDs are not divisible by 8
145571	TDM_IFACE_BLOCK hard-coded in net_conf
145904	Documentation needs to be updated to reflect -X option for disassembler
145979	Undefined symbols when link mixed Ada/C++ programs for cross/works
145982	Ada DUO program using just c should not need c_support
146091	Testmate coverage problem discovered in runtime
146266	lynx profiling is not available in the gui
146513	TDM or kernel linked into high address space may not work
146721	simple_io missing from Apex
146779	[COD] case error at file /ned/rcc/cg.ss/sol.ppc.3_0_1.wrk/rtf_emit.c, line 2
146781	XLINK/LONG_CALL errors when changing NETWORK_TDM_START address
146813	problem with ppc software fp (cg assertion in rtf_preg.c)
147246	"apex link" does not prelink or link in Tornado testing towers
147648	External link fails using pragma Import_Function
147702	Timeout during debugger download
147777	malloc does not return 0
147781	#define HUGE_VAL __infinity() should be placed in the extern C clause
147864	Embedded master index has a bad link for link_block_address
147879	C++ allocator is calling wrong Ada allocator entry
148267	a.cvt: INTERNAL ERROR: while processing arguments
148404	References to Priority Inheritance should be removed
148833	address calculation in gasket for powerpc lynx causes GSK exception
149260	gui should not restart debugger engine after realtime detach
149278	regression 800104 function returning records failing [MID] in Stmt_Gen.Gen_S
149616	No kernel programs never end when using Agilent probe
149618	Cg generates inefficient code for "Li" pseudo-op
150127	Ping does not work from Tools > Target Dialog
150135	rinstall does not report all available Apex Solaris->PPC 3.2.0B releases
150144	GUI Debugger does not work in Host-initiator mode for LynxoS

Table 3 Defects Resolved in Release 3.0.1

Defect	Description	Log Ref.
121088	Default runtime settings used by Apex and instructions for modifying them are now available in a new chapter to the Ada Runtime Guide, "Memory Management."	501169
124974	Previously, the cross linker left an unresolved reference to __BIT_EXTRACT.	509585
127759	File:<SHIFT>Run was not finding the indicated corresponding executable. This has been fixed.
128106	When using Tools > Trace, output was lost if textual output was selected. This has been fixed.
129268	Machine code procedures to which the pragmas Inline_Only and Implicit_Code(Off) have been applied are inclined to fail if they are not inlined. Stricter enforcement of Pragma Inline_Only and more complete error messages fix this.	127951
131091	The Check_Config dialog hangs when invoked from the GUI. This has been fixed.	526497
131159	Shipped BSPs developed on MVME2600 boards with PPCBUG v2.0 failed on updated PPCBUG v3.1 firmware. The BSPs have been corrected.	526246
131294	The compiler key delivered with 2.4.4 and 2.5.0 was missing apex_ada_optim_phase. This is corrected.
131526	V_I_Except.Exception_Name was not returning the correct exception name. This has been fixed.	527646
131995	Previously, users were unable to freeze their own release views because views imported from base were not frozen. Rational now ships frozen views.	528859 544222
132929	Type conversion from an integer type to a modular type when the value is less than zero did not raise Constraint_Error as expected. This has been fixed.	126258 532047
134026	The address calculation for conversion among small enum types was incorrect. This has been fixed
134455	The code generator emitted invalid bounds constants for a conversion from a single precision float value to an unsigned tiny integer. The range check has been corrected to match the destination type size.
140105	When compiling Ada 95 Code, the compiler's middle pass failed with ASSERTION_ERROR. This has been fixed.	540361
140212	Previously, a user defined Read attribute for a non-structured type resulted in a CONSTRAINT_ERROR. This problem has been fixed	535417
140216	Documentation now covers mechanisms for saving scratch registers for all targets.	540499
140341	An unclear error message, RTS Panic: Exception unwinding error...PC saved in __PANIC_EXCEPTION_PC, has been enhanced to print the contents of the PC.
140635	The problems with help windows not opening as expected has been fixed.	541579
141066	The capability to move to and from special-purpose registers has been enhanced. A new intrinsic, Spr(id), takes an arbitrary value in the range 0..1023. Named constant values for the MP750 have also been added. See also defect 141104.	141104
140678	Incorrectly constructed views have resulted in problems acquiring licenses. For example, using Copy_View to create an embedded view from a native view leaves inconsistent properties and policy/switches files. A license cannot be obtained. However, using the command: remodel -update -replace_switches . can update the files and the license becomes available.	541598
140968	Using routines out of /lib/libc.a, for example nanosleep, clock_gettime, = clock_gettime, caused the linker to crash. This has been fixed.
141104	New special-purpose registers are now supported for the NPC650 in the PowerPC Machine_Code package.	141066
141244	Testmate libraries inaccessible in 3.0.0 are now available.
141245	Incorrect float wrappers have been corrected.
141246	rts_vads_exec.ss was shipped as an API. The spec bodies have been restored and, as intended, users can now modify the wrappers.
141247	The incorrect interrupt exit code causing some tasking tests to fail has been fixed.
141505	The Apex_Dialog_Server process did not complete properly when initiated by Tools > Convert, Tools > Target Control, and Tools > Check Config. This problem has been fixed.	543910