Re: draft mcount(3) man page

[Jason Thorpe <thorpej%me.com@localhost>]

> On May 21, 2021, at 5:06 PM, David Holland <dholland-tech%netbsd.org@localhost> wrote:
> 
> 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.

This looks awesome, David, thanks for writing it!

Might it be worth noting some of the historical legacy symbol naming issues that were are the root of the bug report we were just talking about a little while ago?

> 
> 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

-- thorpej