A global SegList tracking utility

   Author:       Thomas Richter <thomas.richter at alumni.tu-berlin.de>, Michael Sinz <enforcer at sinz.org>
   Uploader:     Thomas Richter <thomas richter alumni tu-berlin de>
   Type:         dev/debug
   Version:      47.1
   Requires:     AmigaOS 2.04 or better
   Architecture: m68k-amigaos >= 2.0.4
   Date:         2023-10-01
   Readme:       http://aminet.net/dev/debug/SegTracker.readme
   Downloads:    1516

http://aminet.net/dev/debug/SegTracker.lha

============================================================================

SegTracker

This program is not in the public domain, but may be redistributed

free of charge. See the license conditions at the end of this file.

============================================================================

This is an update of Michael Sinz original SegTracker Utility, based on

the original C code, with many updates included (see below). It is enhanced

and redistributed with the kind permission of Michal Sinz <enforcer at sinz.org>.

While not based on it, this version is also compatible to the v45 SegTracker

by Georg Hörmann, whom I'd like to thank for keeping the project updated.

This version is not based on Georg's source code, though, but an extended

version of Michael's original C code. Georg's fixes were integrated into

this later release.

Make sure you read the documentation before using the program.

New in release 46.1 (note that this version is not based on v45)

----------------------------------------------------------------

- The ROM modules scanner was fixed to depend on the official ROM

size, and no longer depends on second-guessing the ROM area.

- The AmigaOs ROM Updates are no longer checked, though SegTracker

is now aware of LoadModule and the modules it loads.

- Similar to v45.1, installed kick tags are scanned.

- SegTracker now supports overlays and also delivers ordinate

positions of the loaded segments (see below for the interface).

- ROM/Kicktag offsets are fixed, as in the v45 release.

- SegTracker can now be removed again with the REMOVE command line

option.

- SegTracker can now run from the workbench as well, and takes

most command line options as tool types.

- Several race conditions were fixed, such as printing the segment

list or finding segments while segment loading is ungoing.

- The FIND option now also accepts C-style hex numbers starting

with "0x".

- This release provides the same extended interface as v45 to

provide segment type information, though was extended to also

include overlay ordinate information.

New in release 47.1

----------------------------------------------------------------

- SegTracker can now also be instructed to scan binaries for

symbol names and file name and line number information, if

such information is present in the loaded program. Thus,

it includes features of the "FindHit" program which can then

be provided to debugging tools online.

Command line options

----------------------------------------------------------------

SHOW/S: Show the name of all tracked segments.

DUMP/S: More extensive list of all tracked segments and hunks

being tracked, along with ordinate positions for overlays.

FIND/M: Find one or more segments by address. One or multiple

addresses in hex format can be passed in.

NOROM/S: Do not track segments found in the kickstart ROM

(same as v45). Default is to track them.

NOKICKTAG/S: Do not track segments on the exec module list (same as

v45). Default is to track them.

FULLPATH/S: For loaded segments, include the full path of the

loaded program (same as v45).

NOPATH/S: Do not include any path and only the program name

when tracking programs (same as v45).

NOLOADMODULE/S: Do not track segments loaded through LoadModule.

Default is to track LoadModule segments (new in v46).

LOADSYMBOLS/: Additionally, scan loaded segments for debugging

symbols and file name and line number information.

This requires a second pass through the binary as

the Os function ignores both data. (new in v47)

REMOVE/S: Remove a running instance of SegTracker.

Workbench ToolTypes

----------------------------------------------------------------

SHOW,DUMP,NOROM,NOKICKTAG,FULLPATH,NOPATH,NOLOADMODULE,

LOADSYMBOLS,REMOVE:

Same as the Shell command line argument. These tooltypes do not

take any arguments.

WINDOW=<path> Defines the output path where SegTracker should

prints its output do.

Program interface

----------------------------------------------------------------

SegTracker installs a public semaphore (named "SegTracker") into

the exec semaphore list. The structure of the semaphore is as

follows:

typedef UBYTE (* __asm SegTrack(register __a0 ULONG address,

struct SegSem

{

struct SignalSemaphore seg_Semaphore;

SegTrack *seg_Find;

struct MinList seg_List;

UWORD seg_Version;

APTR seg_Self; /* a consistency check */

BPTR seg_Segment; /* internal */

ULONG seg_UseCount; /* internal */

void (*seg_Remove)(void); /* internal */

/* The following members exist if seg_Version >= 47 */

SegTrack *seg_FindSymbol;

ULONG seg_LoadSymbols; /* if set, symbols loaded */

struct MinList seg_Symbols; /* internal */

struct MinList seg_Lines; /* internal */

};

"seg_Find" is a function pointer that, given an address in a0,

returns the name of the program (or name of the segment) the address

belongs to, and the hunk number in *segnum, and the offset of the

address relative to the start of the hunk in *offset.

If segnum and offset are identical (i.e. segnum == offset), then

in this (then single) pointer contains the pointer to the segment

itself, or the pointer to the resident kicktag for ROM tags.

seg_List contains the list of tracked segments. Its structure is

private.

If seg_Self points to seg_Semaphore, seg_Version is the version

of SegTracker, currently v46. Private fields follow that are not

part of the public interface.

SegTracker v46 also supports the extended v45 interface, which is

defined through the UBYTE * returned by seg_Find. If

name = (*seg->Find)(address,&hunk,&offset);

is the return value of seg_Find, and seg_Version is 46 or larger,

then name[-1] contains information on the type of the segment

found.

name[-1] == 0x00: identifies regular segments, and

(*seg->Find)(address,&segment,&segment)

returns in "segment" the pointer to a regular

BPTR-linked segment list.

name[-1] == 0xff: identfies a ROM or KickTag segment, and no

segment linkage should be expected.

name[-1] == 0x01: identifies an overlay segment. The segment

pointer is valid. Additional information

on the overlay ordinate can be obtained as

follows:

ULONG *ord = (ULONG *)(name - 1 - sizeof(ULONG));

ord -= ord[0];

ord[hunk] contains then the ordinate number

of the hunk, i.e. "ord" is an array of

ordinate coordinates indexed by the hunk

number.

Note that ord[] is correctly aligned, i.e.

is an even address.

All other values of name[-1] are reserved for future use.

If seg_Self points back to the semaphore and seg_Version is greater or

equal to 47, an additional function seg_FindSymbol is present. This

function locates the nearest symbol or line number in a source file

given an address into a binary, provided the binary included such

debug information and SegTracker was instructed with the LOADSYMBOLS

command line argument to retrieve them when loading the code.

This function is called as follows to find the nearest debug

symbol in the source code:

symbol = (*seg->FindSymbol)(address,&offset,NULL);

This function returns a NUL-terminated string of the symbol nearest

to "address", or NULL if no such symbol is found. "offset" is

filled by the offset from the symbol.

If the second argument is not NULL, and the function is called

as follows:

file = (*seg->FindSymbol)(address,&offset,&line);

It then returns a NUL-terminated string of the file name where the

supplied address is found, or NULL if no such file could be found. The

offset pointer is filled by the byte offset from the start of the

nearest source code line, and line by the line number from the start

of the file.

------------------------------------------------------------------------------

The THOR-Software Licence (v3, January 2nd 2021)

This License applies to the computer programs known as "SegTracker",

and the corresponding documentation, "SegTracker.doc". The

"Program", below, refers to such program. The "Archive" refers to

the package of distribution, as prepared by the author of the Program,

Thomas Richter. Each licensee is addressed as "you".

The Program and the data in the archive are freely distributable

under the restrictions stated below, but are also Copyright (c)

Thomas Richter.

Distribution of the Program, the Archive and the data in the Archive by a

commercial organization without written permission from the author to any

third party is prohibited if any payment is made in connection with such

distribution, whether directly (as in payment for a copy of the Program) or

indirectly (as in payment for some service related to the Program, or

payment for some product or service that includes a copy of the Program

"without charge"; these are only examples, and not an exhaustive

enumeration of prohibited activities).

However, the following methods of distribution involving payment shall not

in and of themselves be a violation of this restriction:

(i) Distributing the Program on a physical data carrier (e.g. CD-ROM,

DVD, USB-Stick, Disk...) provided that:

a) the Archive is reproduced entirely and verbatim on such data carrier,

including especially this licence agreement;

b) the data carrier is made available to the public for a nominal

fee only, i.e. for a fee that covers the costs of the data carrier,

and shipment of the data carrier;

c) a data carrier with the Program installed is made available to the

author for free except for shipment costs, and

d) provided further that all information on said data carrier is

redistributable for non-commercial purposes without charge.

Redistribution of a modified version of the Archive, the Program or the

contents of the Archive is prohibited in any way, by any organization,

regardless whether commercial or non-commercial. Everything must be kept

together, in original and unmodified form.

Limitations.

THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO

WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE

RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD

THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY

SERVICING, REPAIR OR CORRECTION.

IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE

AND ALL DATA OF THIS ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS

LICENCE BY USING OR REDISTRIBUTING THE PROGRAM.

______________________________________________________________________________

So long,

Thomas Richter (March 2023)

Contents of dev/debug/SegTracker.lha

PERMISSION  UID  GID    PACKED    SIZE  RATIO METHOD CRC     STAMP     NAME
---------- ----------- ------- ------- ------ ---------- ------------ ----------
[unknown]                  279     628  44.4% -lh5- 989a Jan 22  2022 Segtracker.info
[unknown]                 9974   16652  59.9% -lh5- 5b5c Oct  1 12:02 Segtracker/SegTracker
[unknown]                 4312   12726  33.9% -lh5- 2bca Apr 27  2021 Segtracker/SegTracker.doc
[unknown]                  273     523  52.2% -lh5- 8990 Apr 27  2021 Segtracker/SegTracker.doc.info
[unknown]                  403    1172  34.4% -lh5- 2433 Apr 27  2021 Segtracker/SegTracker.info
[unknown]                 4556   11472  39.7% -lh5- 7fa2 Oct  1 12:03 Segtracker/SegTracker.readme
[unknown]                  375     852  44.0% -lh5- 5f02 Apr 27  2021 Segtracker/SegTracker.readme.info
---------- ----------- ------- ------- ------ ---------- ------------ ----------
 Total         7 files   20172   44025  45.8%            Oct  2 04:06