atom_object_management, BuildObj, IsObjBuilt, WriteObj, ReleaseObj - Allows an Atom tool's InstrumentAll routine to build, release, and write objects
Atom's object management routines allow an Atom tool's InstrumentAll routine to build, write, and release objects.
You can use these routines only from an Atom tool's instrumentation file. See atom(1) for a description of Atom.
An InstrumentAll routine must call the BuildObj routine before calling AddCallObj to add analysis routine calls to the object and before traversing the procedures in the object. BuildObj builds the internal data structures Atom uses to manipulate the object. After the Atom tool traverses and instruments the object, the InstrumentAll routine must call the WriteObj routine to write out the instrumented version of the object. For example:
unsigned InstrumentAll(int iargc, char **iargv)
Obj * obj;
for (obj = GetFirstObj(); obj; obj = GetNextObj(obj))
/* instrument obj */
The WriteObj routine writes the instrumented version of the specified object, deallocating the internal data structures BuildObj previously created.
Note that BuildObj may return an error code. It returns a nonzero value (and issues an appropriate error message) if it encounters an error in the executable file for the Obj0. You should propagate this error value back to Atom by returning 1 from InstrumentAll.
The ReleaseObj routine deallocates the internal data structures for the given object, but does not write out the instrumented version the object. You should not call ReleaseObj if you have added any analysis routine calls to the object.
The IsObjBuilt routine returns a nonzero value if the specified object has been built with BuildObj, but not yet written with WriteObj or unbuilt with ReleaseObj.
Whenever possible, tools should build and write out each object only once. Some tools, however, may build and release an object several times, ultimately writing out its instrumented version. This can be very time-consuming for a tool with very large objects.
Similarly, tools should normally build only one object at a time. Certain
tools may simultaneously build several objects, instrument each one, and then
write each out. This has advantages for tools that call
ResolveTargetProc. However, having more
than one large object built at a single time will cause Atom to run slowly
and to consume a large amount of memory.
These routines return values as described above.
Header file containing external definitions of Atom routines
AtomTools: hiprof(5), pixie(5), third(5)
Functions: atom_application_instrumentation(5), atom_application_query(5), atom_application_navigation(5), atom_description_file(5), atom_application_resolvers(5), atom_instrumentation_routines(5), AnalHeapBase(5), Xlate(5)