Hieronymus

Locate where programs are slow!

Hieronymus is a simple statistical profiler: at a given frequency and assisted
by a CPU feature (that provides a hardware source of interrupt), it gets the 
address of the instruction being executed. Then, it finds the associated
process (or library or module) and it tries to identify the function (what
requires to have compiled the object with debug option).

After this sampling, collected data is computed in order to create a report
with 2 parts:
1. a summary with the percentage of time spent in each program
2. a list of functions (with the programs they belong to)

This is enough to identify if an abnormal CPU consumption by a program or
a specific functions. Having this view is the first and mandatory step
before trying to optimize.

This kind of profiler has some advantages:
- it is not necessary to compile with instrumentation options (like -pg), only
  debug option (-g)
- it gives a wide view of the system performance and sometimes a program is not
  slow by itself but because of external libraries or components


Supported platforms
-------------------
Without entering all the details, there are now 3 modes to acquire data,
based on:
- interrupt server, the initial implementation, on G3/G4 machines and Sam4X0
  boards
- performance monitor, the right implementation, that needs its resource built
  into the kernel ; this is the default mode
- software timer, quite experimental and created to circumvent some technical
  constraints ; this mode aims to disappear, at the moment only there to
  provide a kind of working on X1000 (waiting for perf monitor implementation)

So, in terms of supported platforms, we have:
- AmigaOne, Pegasos 2
- Sam 440/460
- A1222/X5000 (new): requires kernel 54.46
- X1000: first implementation, with software timer, one day with the
  performance monitor resource


Usage and options
-----------------
Hieronymus is easy to use. In a console, enter "Hieronymus profile" and start
some activity in the system. Stop it with CTRL-C or it will exit after 30 s
by default.
Note: If no process is currently eating CPU power, much time will be associated
to the kernel task named HAL_idle so in the first summary with programs, an
incredibly high amount of time will be associated to the kernel. That won't
happen if you use a CPU docker that has its own idle task.

Try "Hieronymus help" to find out commands and options.
Basically, commands are:
- help, to display the help
- info, to display information about system components, CPU and caches ...
- profile, to perform sampling and then display a report
- stat, to collect information like cache or TLB misses for example, over
  a given delay (for advanced users)
- version, to give only the version


Features
--------
- Perform system wide profiling without requiring code instrumentation
  (just need to be compiled with debug option)
- Display reports with program and function names (sorted lists based on
  CPU usage) to identify the most greedy parts of the code
- Each run in text mode can be stopped by CTRL-C


History
--------

Version 0.50 (2022-03-10 "Rebirth release")
- Reworked completely the project, for a cleaner code and a better design
- Reworked options, getting inspiration again from perf on Linux
- Added support of A1222/X5000 (requires kernel 54.46)
- Added support of X1000, that basically works but will be consolidated
- Added a new command 'stat' to collect stats for various profiles (CPU, TLB,
  cache, ...) over a given duration
- Improved reporting to easily see in which programs and which functions
  CPU time is spent (now sorted list with decreasing percentage)
- Increased default sampling duration to 30 s, possible to stop with CTRL-C

Version 0.22 (2014-01-03 "Demangling release")
- Added demangling of C++ symbols, useful to make function names readable.
  Also fixed a buffer overflow with very long symbols given by Qt apps using
  for example QWebView class.

Version 0.21 (2013-10-05 "AmigaOne G4 release")
- Added support of AmigaOne models with a G4 processor, that was omitted by
  mistake. Pegasos 2 is detected too but not supported.

Version 0.20 (2012-11-09 "Bourbon release")
- Removed use of performance counters that had no real value
- Added a check of the platform, to see if it is able to profile, to avoid
  a crash. Huge thanks to Max Tretene who fixed the interrupt problem on
  Sam boards, it will be available in a system update, after the Update 5.
- Found how to find the full path of a process started from the shell, with
  no absolute path. The following message should not appear anymore:
  "No info found (wrong file type / offset, program path not found, ...)"

Version 0.16 (2010-01-11 "Birthday release")
- Added use of the performance monitor unit of G3/G4 processors to report 
  cache misses
- Factorized hits grouped by functions (output improvement)
- Handled base address that made some symbols not found due to wrong offsets
- Fixed symbol search that gave wrong function names in the kernel module 
  (now consider only symbols related to functions)

Version 0.10 (2009-12-30 "Genesis release")
- Display profiling information with program and function names
- Provide text mode, full results and summary
- Each run in text mode can be stopped by CTRL-C
- Register to AmiUpdate