| Atom V2.33 Release Notes
========================
A new version of the Atom ADK is available. There were a few bug fixes and
enhancements in V2.33 from the V2.29 release.
Here's a summary of the changes in V2.33:
New Features:
- Floating point support is complete. Analysis routines may now
have floating point arguments. The term FREG must be used
instead of REG when using floating point registers. If you are
currently using floating point registers, and declaring them as
REG, you must change the declarations to FREG.
- Atom has a new flag "-pthread", which uses a thread-safe version
of libc.a, for instrumenting programs that link with libpthread.
This flag is now used in the .threads.desc files of the Hiprof,
Pixie, and Third Degree tools, replacing the previous -Xthreads
flag.
- New instrumentation and analysis routines have been added to
perform thread-safe and per-thread analysis. See the man page
Thread(5). An example of how to write a thread-safe Atom tool is
provided by the /usr/ccs/lib/cmplrs/atom/examples/prof.* files.
- The -[no]threads options has been added to pixie, so it can profile
each thread independently, like other profilers can. The new
-nothreads option has been added to hiprof for consistency.
- The -fork option has been added to Third Degree, Hiprof and Pixie.
Third Degree produces separate .3log files for forked subprocesses
and a separate .3log.sig file for errors in signal handlers that
interrupt regular error reporting. In Hiprof and Pixie, -fork allows
profiling of forked subprocesses without fully instrumenting
libc.so.
Bug Fixes:
- A problem reported with "-gp" and third degree was fixed. If the
application is compiled with "-g" and then instrumented with "-gp",
the function name is now visible in the .3log file (instead of
<unknown>).
- A couple of bugs with line number support were fixed.
- A bug where an assertion was seen due to a block data statement was
fixed.
- A bug was fixed with the -A1 format, which was using the frame
register without setting it.
- Third Degree, Hiprof and Pixie can now handle an indefinite number
of threads and can do so without deadlocking in signal handlers.
- In the Hiprof tool, the bug which caused call-graph entries for
"call_pal" system-calls where no such calls occurred has been fixed.
Atom is now divided into three kits. The ATM350 kit can be installed on
DIGITAL Unix V3.2x. The ATM400 kit can be installed on DIGITAL Unix V4.0x and
V4.2x. The ATM500 kit is available for internal DIGITAL use only, for DIGITAL
Unix Steel BL11 or later. Choose the kit which is appropriate for your
system.
Copyright Notice
================
/****************************************************************************
* *
* COPYRIGHT (c) 1995 BY *
* DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. *
* ALL RIGHTS RESERVED. *
* *
* THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED *
* ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE *
* INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER *
* COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY *
* OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY *
* TRANSFERRED. *
* *
* THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE *
* AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT *
* CORPORATION. *
* *
* DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS *
* SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. *
* *
****************************************************************************
* Copyright 1995 DIGITAL Equipment Corporation
* All Rights Reserved
*
* Permission to use, copy, and modify this software and its documentation is
* hereby granted only under the following terms and conditions. Both the
* above copyright notice and this permission notice must appear in all copies
* of the software, derivative works or modified versions, and any portions
* thereof, and both notices must appear in supporting documentation.
*
* This software may be distributed (but not offered for sale or transferred
* for compensation) to third parties, provided such third parties agree to
* abide by the terms and conditions of this notice.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL
* WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL DIGITAL EQUIPMENT
* CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
* DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
* PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
* ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
* SOFTWARE.
*/
Kit Availability
================
There are three Atom kits, each consists of a single, tar'ed setld package.
You only need one of these kits, depending on what version of the operating
system you have. Use the ATM350 kit for installation on DIGITAL Unix V3.2x.
Use the ATM400 kit for installation on DIGITAL Unix V4.0x - V4.2x. Use the
ATM500 kit for installation on DIGITAL Unix Steel BL11 or later (internal use
only).
You can obtain these kits from one of two locations. All DIGITAL
employees should have anonymous ftp access to this location in Nashua,
NH (USA):
system: alpha.zk3.dec.com
directory: /usr/ftp/pub/prof/tools/atom
files: README - These release notes
ATM350.tar - Atom kit for Unix V3.2x
ATM400.tar - Atom kit for Unix V4.0x - V4.2x
ATM500.tar - Atom kit for Unix Steel BL11 or
later
You may copy the kit from this location with this command:
% ftp alpha.zk3.dec.com
Name: anonymous
Password: <your email address>
ftp> cd pub/prof/tools/atom
ftp> bin
ftp> get ATM350.tar
Everyone (including non-DIGITAL people) should have anonymous ftp access
to this location in Palo Alto, CA (USA):
system: gatekeeper.pa.dec.com
directory: /pub/DEC/WRL/lueck
files: README - These release notes
ATM350.tar - Atom kit for Unix V3.2x
ATM400.tar - Atom kit for Unix V4.0x - V4.2x
ATM500.tar - Atom kit for Unix Steel BL11 or
later
You may copy the kit from this location with this command:
% ftp gatekeeper.pa.dec.com
Name: anonymous
Password: <your email address>
ftp> cd pub/DEC/WRL/lueck
ftp> bin
ftp> get ATM350.tar
For security reasons, read permission has been turned *off* in the
directory containing these files. You can still copy the files, but you
will not be able to list the contents of the directory.
Installation Instructions
=========================
This Atom kit can be installed on the following revisions of the
DIGITAL Unix (formerly known as DEC OSF/1) operating system:
V3.2C (Platinum Lite)
V4.0 (Platinum)
V4.0A (PTA)
V4.0B (PTB)
V4.25 (PTmin)
V4.2 (Steel BL1-BL10)
It may not be installed on earlier revisions. Note, installation on DIGITAL
Unix V4.0x or V4.2x requires the ATM400 kit. Installation on V3.2x releases
requires the ATM350 kit. Installation on Steel BL11 or later requires the
ATM500 kit.
If you intend to create your own tools using Atom (as opposed to using
the supplied tools), make sure the system header files are installed
prior to installing Atom. The system header files are distributed in
the OSFINCLUDE subset, which is on the operating system CD.
Installing on DIGITAL V3.2x
---------------------------
Before installing this kit, make sure you remove any previous versions
of Atom. If you have a previous version of the ATM350 kit, you can
delete it with this command:
% su
# setld -d ATMBASE350 ATMLOADER350 ATMSHLIB350 ATMCXXSHLIB350 \
ATMDFASHLIB350 ATMDPOSHLIB350
If you have a previous version of the ATMBASE300, ATMBASE320, or
ATMBASE340 subsets, you can delete it as you would any other setld kit.
For example:
% su
# setld -d ATMBASE340
NOTE: Do *not* delete the OSFATMBASE or OSFATMBIN subsets. These
subsets are unrelated to Atom.
You are now ready to install the new kit. First, copy the kit as
described above. Then unpack the kit into a temporary directory on your
system:
% cd <temp directory>
% tar xf ATM350.tar
Now, become root and install the kit. Because the installation may
replace some system files, you should not install this kit on a system
with other users loged on.
% su
# setld -l .
This displays a menu of possible subsets to install. There are five
subsets in the Atom kit, but not all systems need all subsets. If a
subset is not needed on your system, it is not displayed in the menu.
Here are the possible subsets you may install:
ATMBASE350 - The base Atom functionality. You must install
this subset.
ATMLOADER350 - A special system loader (/sbin/loader). You
must install this subset in order use Atom to
analyze an application's shared libraries.
This subset is not needed for DIGITAL Unix
V3.2C systems or later.
ATMSHLIB350 - Special versions of the base system and X
windows shared libraries. These libraries do
*not* overwrite the existing libraries on your
system. They are installed in a new directory,
/usr/atomshlib. If you wish to analyze the
base system or X windows shared libraries, you
must install this subset. You must install
the ATMLOADER350 subset in order to install
the ATMSHLIB350 subset. This subset is not
needed for DIGITAL Unix V3.2C systems or later.
ATMCXXSHLIB350 - Special versions of the C++ shared libraries.
These libraries do *not* overwrite the
existing libraries on your system. They are
installed in a new directory, /usr/atomshlib.
You must install this subset if you wish to
instrument the libraries in the C++ runtime.
ATMDFASHLIB350 - Special versions of the Fortran shared
libraries. These libraries do *not* overwrite
the existing libraries on your system. They
are installed in a new directory, /usr/atomshlib.
You must install this subset if you wish to
instrument the libraries in the Fortran
runtime.
ATMDPOSHLIB350 - Special versions of the Pascal shared
libraries. These libraries do *not* overwrite
the existing libraries on your system. They
are installed in a new directory, /usr/atomshlib.
You must install this subset if you wish to
instrument the libraries in the Pascal runtime.
Unless you have DIGITAL Unix V3.2C or later, it is recommended that you
install at least the ATMBASE350, ATMLOADER350, and ATMSHLIB350 subsets.
Some tools will automatically analyze all of an application's shared
libraries. This will only work if all three of these subsets are
installed.
The installation process replaces several of your system files:
/usr/ccs/lib/cmplrs/cc/ld
/usr/ccs/lib/cmplrs/cc/libmld.a
/usr/ccs/lib/cmplrs/cc/prof
/usr/ccs/lib/cmplrs/cc/gprof
/usr/ccs/lib/cmplrs/cc/pixstats
/sbin/loader (if you install ATMLOADER350)
The original versions of these files are saved when you install the
subset. If you delete the subset, the original versions are put back in
place.
After you install the Atom kit, you may delete the temporary directory
where you unpacked the kit:
% rm -rf <temp directory>
You may also wish to run the installation verification programs.
However, make sure you have a fair amount of /tmp space. If not, set
the TMPDIR environment variable to point to a larger partition (for
example, /usr/tmp).
% su
# setld -v ATMBASE350
The verification programs pass if they print the following line:
Confidence test suite passed.
If you installed the ATMSHLIB subset:
# setld -v ATMCXXSHLIB350
# setld -v ATMDFASHLIB350
# setld -v ATMDPOSHLIB350
If you install the ATMLOADER350 subset, you may want to reboot your
system. Doing so releases some system resources and improves
performance.
Installing on DIGITAL Unix V4.0x - V4.2x
----------------------------------------
Before installing this kit, make sure you remove any previous versions
of Atom:
% su
# setld -d ATMBASE400
If this command returns an error, don't worry. That simply means you
don't have an old version of the Atom kit installed, no harm has been
done.
NOTE: Do *not* delete the OSFATMBASE or OSFATMBIN subsets. These
subsets are unrelated to Atom.
You are now ready to install the new kit. First, copy the kit as
described above. Then unpack the kit into a temporary directory on your
system:
% cd <temp directory>
% tar xf ATM400.tar
Now, become root and install the kit. Because the installation may
replace some system files, you should not install this kit on a system
with other users loged on.
% su
# setld -l .
This displays a menu of possible subsets to install. There is only one
subset to choose. Your operating system already has all the necessary
support for Atom.
ATMBASE400 - The base Atom functionality. You must install
this subset.
After you install the Atom kit, you may delete the temporary directory
where you unpacked the kit:
% rm -rf <temp directory>
There is no need to reboot the system after installing this subset.
You may also wish to run the installation verification programs.
However, make sure you have a fair amount of /tmp space. If not, set
the TMPDIR environment variable to point to a larger partition (for
example, /usr/tmp).
% su
# setld -v ATMBASE400
The verification program passes if it prints the following line:
Confidence test suite passed.
Uninstalling from DIGITAL Unix V4.0
-----------------------------------
Should you want to remove the ATM400 kit from a DIGITAL Unix V4.0 system
and revert to the original version of Atom, you can follow this
procedure. First remove the ATM400 kit:
% su
# setld -d ATMBASE400
Then remove the OSFPGMR400 and OSFSDE400 subsets, these were partially
overwritten by the ATM400 kit:
# setld -d OSFPGMR400 OSFSDE400
Finally, reinstall the OSFPGMR400 and OSFSDE400 subsets:
# setld -l <device> OSFPGMR400 OSFSDE400
where <device> is either your CD rom device or the name of your ris
area, depending on your distribution media. See the setld(8) manpage
for more information on loading subsets.
Installing on DIGITAL Unix Steel BL11 or later
----------------------------------------------
Before installing this kit, make sure you remove any previous versions
of Atom:
% su
# setld -d ATMBASE500
If this command returns an error, don't worry. That simply means you
don't have an old version of the Atom kit installed, no harm has been
done.
NOTE: Do *not* delete the OSFATMBASE or OSFATMBIN subsets. These
subsets are unrelated to Atom.
You are now ready to install the new kit. First, copy the kit as
described above. Then unpack the kit into a temporary directory on your
system:
% cd <temp directory>
% tar xf ATM500.tar
Now, become root and install the kit. Because the installation may
replace some system files, you should not install this kit on a system
with other users loged on.
% su
# setld -l .
This displays a menu of possible subsets to install. There is only one
subset to choose. Your operating system already has all the necessary
support for Atom.
ATMBASE500 - The base Atom functionality. You must install
this subset.
After you install the Atom kit, you may delete the temporary directory
where you unpacked the kit:
% rm -rf <temp directory>
There is no need to reboot the system after installing this subset.
You may also wish to run the installation verification programs.
However, make sure you have a fair amount of /tmp space. If not, set
the TMPDIR environment variable to point to a larger partition (for
example, /usr/tmp).
% su
# setld -v ATMBASE500
The verification program passes if it prints the following line:
Confidence test suite passed.
Uninstalling from DIGITAL Unix Steel BL11 or later
--------------------------------------------------
Should you want to remove the ATM500 kit from a DIGITAL Unix system
and revert to the original version of Atom, you can follow this
procedure. First remove the ATM500 kit:
% su
# setld -d ATMBASE500
Then remove the OSFPGMR500 and OSFSDE500 subsets, these were partially
overwritten by the ATM500 kit:
# setld -d OSFPGMR500 OSFSDE500
Finally, reinstall the OSFPGMR500 and OSFSDE500 subsets:
# setld -l <device> OSFPGMR500 OSFSDE500
where <device> is either your CD rom device or the name of your ris
area, depending on your distribution media. See the setld(8) manpage
for more information on loading subsets.
Documentation
=============
The following manpages should be available on your system:
atom(1)
hiprof(5)
pixie(5)
third(5)
atom_application_instrumentation(5)
atom_application_navigation(5)
atom_application_query(5)
atom_application_resolvers(5)
atom_instrumentation_routines(5)
atom_object_management(5)
atom_description_file(5)
Xlate(5)
AnalHeapBase(5)
Thread(5)
NOTE: Your system may already have a pixie(1) manpage installed. To
view the new pixie(5) manpage, type
% man 5 pixie
If you install the ATM350 kit, the following postscript manual is also
included. It describes how to develop Atom tools and also how to use
the Third Degree tool.
/usr/lib/cmplrs/atom/doc/atomprog.ps
This manual consists of two chapters taken from the DIGITAL Unix V4.0
Programmer's Guide. If you installed the ATM400 or ATM500 kit, your version
of the Programmer's Guide already contains these chapters.
Requirements for Running Atom
=============================
In order to run Atom on an application, you must relink that application
with a recent version of the linker. Applications linked on DIGITAL
Unix V4.0 are ready to be processed with Atom. Applications linked on
previous versions should be relinked with the linker that is installed
by this kit. Remember to also relink any shared libraries that your
application uses.
If you attempt to run Atom on an image that has not been linked with a
current linker, Atom complains with either an error or a warning
message and tells you to relink the image. If the image was linked with
a very old linker, Atom issues an error and stops. If the image was
linked with a moderately old linker, Atom issues a warning and
continues. If you get this warning and the instrumented image does not
run properly, relink the image before submitting a bug report. The
problem is likely due to the old linker.
Some large applications are built with several link steps. In one step,
small object modules may be combined into large object modules by using
the linker's "-r" switch like this:
% ld -r -o bigobj1.o obj1.o obj2.o obj3.o ...
In a subsequent step, the large object modules are linked into an
application like this:
% ld -o myapp bigobj1.o bigobj2.o bigobj3.o ...
If your application does this, *all* link steps must be performed with
a recent linker.
NOTE: This multi-step link process is different from combining
object modules together into archive libraries. There is
no need to rerun the "ar" command if you combine multiple
object modules into archive libraries.
Special Shared Libraries
========================
Read this section if you installed the ATMSHLIB350, ATMCXXSHLIB350,
ATMDFASHLIB350, or ATMDPOSHLIB350 subsets. If you did not install these
subsets, you may skip this section.
The four subsets listed above provide versions of the system shared
libraries that have been linked with the new linker. These libraries are
installed in the /usr/atomshlib directory. If your application uses
shared libraries, it must use these versions.
NOTE: These shared libraries are provided as a convenience to
users of Atom on old operating systems. They are not
officially supported. Do not enter bugs against these
versions of the libraries. If you have problems with
these libraries, let me know directly (see "Reporting
Bugs" below).
Before applying Atom to your application, you should first verify that
your application works correctly with these new shared libraries.
Verify this by doing the following:
% setenv LD_LIBRARY_PATH /usr/atomshlib
Then run your application. If things work OK, proceed to run Atom on
your application. For example, if you are using the Third Degree tool:
% atom myapp -tool third -L/usr/atomshlib
The "-L/usr/atomshlib" switch tells Atom to use the shared libraries in
the /usr/atomshlib directory. Then, run the instrumented application as
you normally would, for example:
% setenv LD_LIBRARY_PATH .:/usr/atomshlib
% myapp.third
Kernel Support
==============
This version of Atom allows you to instrument the DIGITAL Unix kernel.
For more information about this, please contact Alan Eustace at WRL:
Alan Eustace
[email protected]
DTN 543-3312
(415) 617-3312
Reporting Bugs
==============
If you find a bug in Atom, please send a description of your problem to
[email protected].
Please include the following information in any bug report:
* The version of Atom, which is obtained with this command:
% atom -version
* The version of the operating system, which is obtained with
this command:
% uname -a
* A list of those Atom subsets that are installed, which is
obtained with this command:
% /usr/sbin/setld -i | grep '^ATM'
* A description of the problem including the exact command line
you passed to Atom.
* If the problem is with a tool you wrote, either include the
sources for the tool's instrumentation and analysis code or
provide a pointer to the sources. If you are using one of the
prepackaged tools in the Atom kit, you need not provide this
information.
* I normally need the binary image of the application to which
you applied Atom. If possible, save a copy and provide a
pointer to the application.
Using OM with Atom
==================
There are some issues to be aware of if you use the -om compiler switch.
Applications compiled or linked with -om cannot be processed with Atom.
This is a limitation in the development environment that will be
addressed in the future.
There is an additional compatibility problem on DIGITAL Unix V3.2x if you
use the -WL,-om_ireorg_feedback switch with -om. The -WL,-om_ireorg_feedback
switch causes OM to read pixie-generated .Addrs and .Counts files. However,
the .Addrs and .Counts files generated by the Atom-based pixie tool are in
a different format from the files recognized by OM. In order to work around
this problem, you can use the updated version of OM that is supplied in this
kit. To use this updated version, add these switches to your compiler command
line:
-tL -B.atmbase
For example:
% cc -tL -B.atmbase -om -WL,-om_ireorg_feedback,foobar foobar.c
The updated version of OM understands both the new and old versions of
the .Addrs and .Counts files. Note, this issue is not a problem on
DIGITAL Unix V4.0x or V4.2x.
[Posted by WWW Notes gateway]
|