Copy head (r256279) to stable/10 as part of the 10.0-RELEASE cycle.

Approved by: re (implicit)
Sponsored by: The FreeBSD Foundation

Update nsamples and nbuffers defaults to match reality.

Fix typos, spelling, formatting and mdoc mistakes found by Nobuyuki while
translating these manual pages. Minor corrections by me.

Submitted by: Nobuyuki Koganemaru <n-kogane@syd.odn.ne.jp>

mdoc: move CAVEATS, BUGS and SECURITY CONSIDERATIONS sections to the
bottom of the manpages and order them consistently.

GNU groff doesn't care about the ordering, and doesn't even mention
CAVEATS and SECURITY CONSIDERATIONS as common sections and where to put
them.

Found by: mdocml lint run
Reviewed by: ru

Document changes in behaviour due to sparse CPU numbering support.

Document the PMC_F_CALLCHAIN flag and the kern.hwpmc.callchaindepth
tunable.

Sponsored by: FreeBSD Foundation and Google Inc.

- Document an EAGAIN error return from a PMC_OP_CONFIGURELOG request.
- Document some EINVAL error returns from PMC_OP_CONFIGURELOG,
PMC_OP_WRITELOG and PMC_OP_FLUSHLOG that were missed earlier.
- Correct a typo: s/PMC_OP_ALLOCATE/PMC_OP_PMCALLOCATE/.
- Describe how log file writing errors are returned by a PMC_OP_FLUSHLOG
request.

- Improve clarity: use 'scope' to distinguish between process and system
PMCs and 'mode' to distinguish between counting and sampling.
- Document PMC row dispositions.
- Document the requirement for PRIV_PMC_MANAGE privilege when issuing
PMC_OP_PMCADMIN requests.

- Correct a documentation bug: handles returned from a PMC_OP_PMCALLOCATE
request are 32 bit values, and are not necessarily small.
- Note that the PMC_F_KGMON flag is currently unimplemented.
- Tweak description of an EINVAL error return.
- Add an "AUTHORS" section.

Describe an error return that was missed out earlier.

Improve a sentence.

Prodded by: billf
MFC after: 3 days

Spelling/grammar fixes.

MFC after: 1 week

Typo fix; "ing" -> "in".

Document the EOPNOTSUPP returned by hwpmc(4) if a sampling mode PMC
is requested on a CPU without an APIC.

Requested by: anholt (a while ago)

-mdoc sweep.

Note the requirement for 'device apic' on i386 systems. [1]

Consistently use 'x86' when referring to behaviour common to the
i386 and amd64.

Submitted by: Niklas Sorensson <nik@cs.chalmers.se> [1]

Correct a typo.

MFC after: 3 days

Document the diagnostic message printed at startup time. Keep the
list of diagnostic messages sorted.

Document the recently introduced EOPNOTSUPP error return. Repair
sort ordering for the list of error descriptions.

MFC after: 3 days

Document two new diagnostic messages in hwpmc(4).

Add COMPATIBILITY and HISTORY sections. Fix an -mdoc error.
Cross-reference pmclog(3).

Reviewed by: ru

Fix typos and use consistent section names in manual pages:

s/SYSCTLS/SYSCTL VARIABLES/
s/TUNABLES/LOADER TUNABLES/
s/CAVEAT/CAVEATS/
s/DESCIPTION/DESCRIPTION/

Reviewed by: ru
MFC after: 3 days

Fix markup, correct typos, improve grammar, move the BUGS section to
the end of the manual page.

Submitted by: ru
Approved by: re (blanket hwpmc)

Correct spelling of options PMC_HOOKS to options HWPMC_HOOKS.

Approved by: re (man page blanket)

Document the need for a log file to be configured before a PMC
configured with logging options can be started.

MFP4:

- Implement sampling modes and logging support in hwpmc(4).

- Separate MI and MD parts of hwpmc(4) and allow sharing of
PMC implementations across different architectures.
Add support for P4 (EMT64) style PMCs to the amd64 code.

- New pmcstat(8) options: -E (exit time counts) -W (counts
every context switch), -R (print log file).

- pmc(3) API changes, improve our ability to keep ABI compatibility
in the future. Add more 'alias' names for commonly used events.

- bug fixes & documentation.

Add convenience APIs pmc_width() and pmc_capabilities() to -lpmc.
Have pmcstat(8) and pmccontrol(8) use these APIs.

Return PMC class-related constants (PMC widths and capabilities)
with the OP GETCPUINFO call leaving OP PMCINFO to return only the
dynamic information associated with a PMC (i.e., whether enabled,
owner pid, reload count etc.).

Allow pmc_read() (i.e., OPS PMCRW) on active self-attached PMCs to
get upto-date values from hardware since we can guarantee that the
hardware is running the correct PMC at the time of the call.

Bug fixes:
- (x86 class processors) Fix a bug that prevented an RDPMC
instruction from being recognized as permitted till after the
attached process had context switched out and back in again after
a pmc_start() call.

Tighten the rules for using RDPMC class instructions: a GETMSR
OP is now allowed only after an OP ATTACH has been done by the
PMC's owner to itself. OP GETMSR is not allowed for PMCs that
track descendants, for PMCs attached to processes other than
their owner processes.

- (P4/HTT processors only) Fix a bug that caused the MI and MD
layers to get out of sync. Add a new MD operation 'get_config()'
as part of this fix.

- Allow multiple system-mode PMCs at the same row-index but on
different CPUs to be allocated.

- Reject allocation of an administratively disabled PMC.

Misc. code cleanups and refactoring. Improve a few comments.

Bring a working snapshot of hwpmc(4), its associated libraries, userland utilities
and documentation into -CURRENT.

Bump FreeBSD_version.

Reviewed by: alc, jhb (kernel changes)