.TH ppchcalls 8  "2022-10-19" "USER COMMANDS"
.SH NAME
ppchcalls \- Summarize ppc hcall counts and latencies.
.SH SYNOPSIS
.B ppchcalls [-h] [-p PID] [-t TID] [-i INTERVAL] [-d DURATION] [-T TOP] [-x] [-e ERRNO] [-L] [-m] [-P] [-l] [--hcall HCALL]
.SH DESCRIPTION
This tool traces hcall entry and exit raw tracepoints and summarizes either the
number of hcalls of each type, or the number of hcalls per process. It can
also collect min, max and average latency for each hcall or each process.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bcc. Linux 4.17+ is required to attach a BPF program to the
raw_hcalls:hcall_{enter,exit} tracepoints, used by this tool.
.SH OPTIONS
.TP
\-h
Print usage message.
.TP
\-p PID
Trace only this process.
.TP
\-t TID
Trace only this thread.
.TP
\-i INTERVAL
Print the summary at the specified interval (in seconds).
.TP
\-d DURATION
Total duration of trace (in seconds).
.TP
\-T TOP
Print only this many entries. Default: 10.
.TP
\-x
Trace only failed hcalls (i.e., the return value from the hcall was < 0).
.TP
\-e ERRNO
Trace only hcalls that failed with that error (e.g. -e EPERM or -e 1).
.TP
\-m
Display times in milliseconds. Default: microseconds.
.TP
\-P
Summarize by process and not by hcall.
.TP
\-l
List the hcalls recognized by the tool (hard-coded list). Hcalls beyond this
list will still be displayed, as "[unknown: nnn]" where nnn is the hcall
number.
.TP
\--hcall HCALL
Trace this hcall only (use option -l to get all recognized hcalls).
.SH EXAMPLES
.TP
Summarize all hcalls by hcall:
#
.B ppchcalls
.TP
Summarize all hcalls by process:
#
.B ppchcalls \-P
.TP
Summarize only failed hcalls:
#
.B ppchcalls \-x
.TP
Summarize only hcalls that failed with EPERM:
#
.B ppchcalls \-e EPERM
.TP
Trace PID 181 only:
#
.B ppchcalls \-p 181
.TP
Summarize hcalls counts and latencies:
#
.B ppchcalls \-L
.SH FIELDS
.TP
PID
Process ID
.TP
COMM
Process name
.TP
HCALL
Hcall name, or "[unknown: nnn]" for hcalls that aren't recognized
.TP
COUNT
The number of events
.TP
MIN
The minimum elapsed time (in us or ms)
.TP
MAX
The maximum elapsed time (in us or ms)
.TP
AVG
The average elapsed time (in us or ms)
.SH OVERHEAD
For most applications, the overhead should be manageable if they perform 1000's
or even 10,000's of hcalls per second. For higher rates, the overhead may
become considerable.
.
.SH SOURCE
This is from bcc.
.IP
https://github.com/iovisor/bcc
.PP
Also look in the bcc distribution for a companion _examples.txt file containing
example usage, output, and commentary for this tool.
.SH OS
Linux
.SH STABILITY
Unstable - in development.
.SH AUTHOR
Harsh Prateek Bora
.SH SEE ALSO
syscount(8)