draft mcount(3) man page

[David Holland <dholland-tech%netbsd.org@localhost>]

The workings of the various *mcount functions are confusing and
currently undocumented. After wading into it just now for I think the
third time recently, I wrote the following to ease the process.

Comments?

   ------
.\"
.\" Copyright (c) 2021 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by David A. Holland.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 21, 2021
.Dt MCOUNT 3
.Os
.Sh NAME
.Nm mcount ,
.Nm _mcount ,
.Nm __mcount
.Nd profiling hooks
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.Fn _mcount "/* asmlinkage */"
.Fn __mcount "u_long frompc" "u_long selfpc"
.Sh DESCRIPTION
The
.Fl pg
option to
.Xr cc 1
causes the compiler to insert calls to a profiling hook
at the entry to each function it compiles.
This allows code in the standard library to collect call graph
information.
.Pp
The compiler inserts a call to
.Fn _mcount ,
typically written in assembler, which is responsible for saving
registers and calling
.Fn __mcount .
.Pp
Note however that on some targets, e.g. vax, these names are
reversed.
The name of what this manual page refers to as
.Fn _mcount
is determined by the compiler, and the name of what this manual
page refers to as
.Fn __mcount
is determined by the macro
.Dv MCOUNT_DECL
in
.In machine/profile.h
(q.v.).
.Pp
The
.Ar frompc
argument to
.Nm __mcount
is the address the call came from, that is, the original return
address; the
.Ar selfpc
argument is the address of the callee, normally expressed as the
return address of the call to
.Nm _mcount .
Note that
.Nm _mcount
itself does not have arguments in the normal sense; it receives stack
and register contents consistent with the call location inserted by
the compiler, which is usually at the beginning of the original
function but may vary by target.
It is responsibile for extracting the arguments to
.Nm __mcount
from that state, in addition to preserving register contents as
needed.
.Pp
The code for
.Nm _mcount
is on some machines contained in the macro
.Dv MCOUNT
in
.In machine/profile.h ,
and on others in its own source file.
In the former case,
.Nm __mcount
can be and often is declared static.
.Sh RETURN VALUES
None.
.Sh RESTRICTIONS
Both
.Nm _mcount
and
.Nm __mcount
are internal interfaces and must not be called directly by application
code.
The symbols are not even guaranteed to exist unless the
.Fl pg
option was given to
.Xr cc 1 .
This manual page is provided to document the internal workings for
developers who need to adjust them.
   ------

-- 
David A. Holland
dholland%netbsd.org@localhost