svn commit: r44555 - in head/en_US.ISO8859-1/books/handbook: config dtrace
Dru Lavigne
dru at FreeBSD.org
Mon Apr 14 18:39:13 UTC 2014
Author: dru
Date: Mon Apr 14 18:39:12 2014
New Revision: 44555
URL: http://svnweb.freebsd.org/changeset/doc/44555
Log:
Prep work for merging Power and Resource Management and Using and
Debugging FreeBSD ACPI
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/config/chapter.xml
head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Apr 14 17:44:45 2014 (r44554)
+++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Apr 14 18:39:12 2014 (r44555)
@@ -2838,57 +2838,25 @@ kern.maxvnodes: 100000</screen>
</info>
<para>It is important to utilize hardware resources in an
- efficient manner. Before the Advanced Configuration and Power
- Interface (<acronym>ACPI</acronym>) was introduced, it was
- difficult and inflexible for operating systems to manage the
- power usage and thermal properties of a system. The hardware
- was managed by the <acronym>BIOS</acronym> and the user had less
- control and visibility into the power management settings. Some
- limited configurability was available via <emphasis>Advanced
- Power Management (<acronym>APM</acronym>)</emphasis>. Power
- and resource management allows the operating system to monitor
- system limits and to possibly provide an alert if the system
- temperature increases unexpectedly.</para>
-
- <para>This section provides comprehensive information about
- <acronym>ACPI</acronym>. References will be provided for
- further reading.</para>
-
- <sect2 xml:id="acpi-intro">
- <title>What Is ACPI?</title>
-
- <indexterm>
- <primary>ACPI</primary>
- </indexterm>
-
- <indexterm>
- <primary>APM</primary>
- </indexterm>
-
- <para><acronym>ACPI</acronym> is a standard written by an
- alliance of vendors to provide a standard interface for
- hardware resources and power management. It is a key
- element in <emphasis>Operating System-directed configuration
- and Power Management</emphasis> as it provides more control
- and flexibility to the operating system. Modern systems
- <quote>stretched</quote> the limits of the current Plug and
- Play interfaces prior to the introduction of
- <acronym>ACPI</acronym>. <acronym>ACPI</acronym> is the
- direct successor to <acronym>APM</acronym>.</para>
- </sect2>
-
- <sect2 xml:id="acpi-old-spec">
- <title>Shortcomings of Advanced Power Management</title>
-
- <para>The <acronym>APM</acronym> facility controls the power
- usage of a system based on its activity. The
- <acronym>APM</acronym> <acronym>BIOS</acronym> is supplied
- by the vendor and is specific to the hardware platform. An
- <acronym>APM</acronym> driver in the operating system
- mediates access to the <emphasis><acronym>APM</acronym>
- Software Interface</emphasis>, which allows management of
- power levels. <acronym>APM</acronym> should still be used
- for systems manufactured at or before the year 2000.</para>
+ efficient manner. Power and resource management allows the
+ operating system to monitor system limits and to possibly
+ provide an alert if the system temperature increases
+ unexpectedly. An early specification for providing power
+ management was the Advanced Power Management
+ (<acronym>APM</acronym>) facility. <acronym>APM</acronym>
+ controls the power usage of a system based on its activity.
+ However, it was difficult and inflexible for operating systems
+ to manage the power usage and thermal properties of a system.
+ The hardware was managed by the <acronym>BIOS</acronym> and the
+ user had limited configurability and visibility into the power
+ management settings. The <acronym>APM</acronym>
+ <acronym>BIOS</acronym> is supplied by the vendor and is
+ specific to the hardware platform. An <acronym>APM</acronym>
+ driver in the operating system mediates access to the
+ <acronym>APM</acronym> Software Interface, which allows
+ management of power levels. <acronym>APM</acronym> should still
+ be used for systems manufactured at or before the year
+ 2000.</para>
<para>There are four major problems in <acronym>APM</acronym>.
First, power management is done by the vendor-specific
@@ -2918,11 +2886,37 @@ kern.maxvnodes: 100000</screen>
many situations. <acronym>PNPBIOS</acronym> is 16-bit
technology, so the operating system has to use 16-bit
emulation in order to interface with
- <acronym>PNPBIOS</acronym> methods.</para>
-
- <para>The &os; <acronym>APM</acronym> driver is documented in
+ <acronym>PNPBIOS</acronym> methods. &os; provides an
+ <acronym>APM</acronym> driver for backwards compatibility with
+ older hardware. The driver is documented in
&man.apm.4;.</para>
- </sect2>
+
+ <indexterm>
+ <primary>ACPI</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>APM</primary>
+ </indexterm>
+
+ <para>The successor to <acronym>APM</acronym> is the Advanced
+ Configuration and Power Interface (<acronym>ACPI</acronym>).
+ <acronym>ACPI</acronym> is a standard written by an
+ alliance of vendors to provide a standard interface for
+ hardware resources and power management. It is a key
+ element in <emphasis>Operating System-directed configuration
+ and Power Management</emphasis> as it provides more control
+ and flexibility to the operating system. Modern systems
+ stretched the limits of the current Plug and
+ Play interfaces prior to the introduction of
+ <acronym>ACPI</acronym>..</para>
+
+ <para>This chapter demonstrates how to configure
+ <acronym>ACPI</acronym> on &os;. It then offers some tips on
+ how to debug <acronym>ACPI</acronym> and how to submit a
+ problem report containing debugging information so that
+ developers can diagnosis and fix <acronym>ACPI</acronym>
+ issues.</para>
<sect2 xml:id="acpi-config">
<title>Configuring <acronym>ACPI</acronym></title>
@@ -2963,11 +2957,10 @@ kern.maxvnodes: 100000</screen>
<para>Other options are available via &man.sysctl.8;. Refer to
&man.acpi.4; and &man.acpiconf.8; for more information.</para>
</sect2>
- </sect1>
- <sect1 xml:id="ACPI-debug">
+ <sect2 xml:id="ACPI-submitdebug">
<info>
- <title>Using and Debugging &os; <acronym>ACPI</acronym></title>
+ <title>Debugging &os; <acronym>ACPI</acronym></title>
<authorgroup>
<author>
@@ -3018,9 +3011,6 @@ kern.maxvnodes: 100000</screen>
cause of problems and in debugging and developing a
solution.</para>
- <sect2 xml:id="ACPI-submitdebug">
- <title>Submitting Debugging Information</title>
-
<note>
<para>Before submitting a problem, ensure the latest
<acronym>BIOS</acronym> version is installed and, if
Modified: head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml Mon Apr 14 17:44:45 2014 (r44554)
+++ head/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml Mon Apr 14 18:39:12 2014 (r44555)
@@ -35,9 +35,10 @@ that might make this chapter too large.
<para>&dtrace;, also known as Dynamic Tracing, was developed by
&sun; as a tool for locating performance bottlenecks in
- production and pre-production systems. It is not, in any way,
- a debugging tool, but a tool for real time system analysis to
- locate performance and other issues.</para>
+ production and pre-production systems. In addition to
+ diagnosing performance problems, &dtrace; can be used to help
+ investigate and debug unexpected behavior in both the &os;
+ kernel and in userland programs.</para>
<para>&dtrace; is a remarkable profiling tool, with an impressive
array of features for diagnosing system issues. It may also
@@ -45,6 +46,17 @@ that might make this chapter too large.
capabilities. Users may even author their own utilities using
the &dtrace; D Language, allowing them to customize their
profiling based on specific needs.</para>
+
+ <para>The &dtrace; implementation in &os; provides experimental
+ support for userland &dtrace;. This feature allows users to
+ perform function boundary tracing for userland programs using
+ the <literal>pid</literal> provider, and to insert static probes
+ into userland programs for later tracing. Some ports, such as
+ <package>databases/postgres-server</package> and
+ <package>lang/php5</package> have a &dtrace; option to enable
+ static probes. &os; 10.0-RELEASE has reasonably good userland
+ &dtrace; support, but it is not considered production ready. In
+ particular, it is possible to crash traced programs.</para>
<para>After reading this chapter, you will know:</para>
@@ -72,12 +84,6 @@ that might make this chapter too large.
</listitem>
<listitem>
- <para>Be familiar with
- the basics of kernel configuration/compilation
- (<xref linkend="kernelconfig"/>).</para>
- </listitem>
-
- <listitem>
<para>Have some familiarity with security and how it
pertains to &os; (<xref linkend="security"/>).</para>
</listitem>
@@ -87,18 +93,6 @@ that might make this chapter too large.
(<xref linkend="updating-upgrading"/>).</para>
</listitem>
</itemizedlist>
-
- <!--
- Temporary warning to avoid listing experimental versions
- and production versions of FreeBSD with this technology.
- -->
- <warning>
- <para>This feature is considered experimental. Some options
- may be lacking in functionality, other parts may not work
- at all. In time, this feature will be considered production
- ready and this documentation will be altered to fit that
- situation.</para>
- </warning>
</sect1>
<sect1 xml:id="dtrace-implementation">
@@ -106,9 +100,15 @@ that might make this chapter too large.
<para>While the &dtrace; in &os; is similar to that found in
&solaris;, differences do exist. The primary difference is that
- on &os;, &dtrace; needs to be specifically enabled by loading
- kernel modules or by compiling a custom kernel with specific
- options.</para>
+ in &os;, &dtrace; is implemented as a set of kernel modules and
+ &dtrace; can not be used until the modules are loaded. To load
+ all of the necessary modules:</para>
+
+ <screen>&prompt.root; <userinput>kldload dtraceall</userinput></screen>
+
+ <para>Beginning with &os; 10.0-RELEASE, the modules are
+ automatically loaded when <command>dtrace</command> is
+ run.</para>
<para>&os; uses the <literal>DDB_CTF</literal> kernel option
to enable support for loading <acronym>CTF</acronym>
@@ -127,7 +127,14 @@ that might make this chapter too large.
<para>Some different providers exist for &os; than for &solaris;.
Most notable is the <literal>dtmalloc</literal> provider, which
allows tracing <function>malloc()</function> by type in the
- &os; kernel.</para>
+ &os; kernel. Some of the providers found in &solaris;, such as
+ <literal>cpc</literal> and <literal>mib</literal>, are not
+ present in &os;. These may appear in future versions of &os;.
+ Moreover, some of the providers available in both operating
+ systems are not compatible, in the sense that their probes have
+ different argument types. Thus, <acronym>D</acronym> scripts
+ written on &solaris; may or may not work unmodified on &os;, and
+ vice versa.</para>
<para>Due to security differences, only <systemitem
class="username">root</systemitem> may use &dtrace; on &os;.
@@ -151,78 +158,52 @@ that might make this chapter too large.
<sect1 xml:id="dtrace-enable">
<title>Enabling &dtrace; Support</title>
- <para>To enable support for &dtrace;, add the following lines to
- the kernel configuration file:</para>
+ <para>In &os; 9.2 and 10.0, &dtrace; support is built into the
+ <filename>GENERIC</filename> kernel. Users of earlier versions
+ of &os; or who prefer to statically compile in &dtrace; support
+ should add the following lines to a custom kernel configuration
+ file and recompile the kernel using the instructions in <xref
+ linkend="kernelconfig"/>.</para>
<programlisting>options KDTRACE_HOOKS
options DDB_CTF</programlisting>
<note>
- <para>Users of the AMD64 architecture will want to add the
- following line to their kernel configuration file:</para>
+ <para>Users of the AMD64 architecture should also add this
+ line:</para>
<programlisting>options KDTRACE_FRAME</programlisting>
- <para>This option provides support for the
- <acronym>FBT</acronym> feature. &dtrace; will work without
- this option; however, there will be limited support for
+ <para>This option provides support for
+ <acronym>FBT</acronym>. While &dtrace; will work without
+ this option, there will be limited support for
function boundary tracing.</para>
</note>
- <para>All sources must be rebuilt and installed with
- <acronym>CTF</acronym> options.</para>
-
- <note>
- <para>Starting from 10.0, the following steps are not needed any
- more as the <literal>WITH_CTF</literal> option is included in
- the <filename>GENERIC</filename> kernel configuration.</para>
- </note>
-
- <para>To accomplish this task, rebuild the &os; sources
- using:</para>
-
- <!-- XXXTR: WITH_CTF has been reported to leave a user with a
- broken system when used with buildworld. Until this is
- fixed, comment out those parts. When uncommenting, kill
- the extra screen.
- -->
-
- <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-<!-- &prompt.root; <userinput>make WITH_CTF=1 buildworld</userinput> -->
-&prompt.root; <userinput>make WITH_CTF=1 kernel</userinput></screen>
-
-<!-- &prompt.root; <userinput>make WITH_CTF=1 installworld</userinput>
-&prompt.root; <userinput>mergemaster -Ui</userinput></screen> -->
-
- <para>The system will need to be restarted.</para>
-
- <para>After rebooting and allowing the new kernel to be loaded
- into memory, support for the Korn shell should be added. This
+ <para>Once the &os; system has rebooted into the new kernel, or
+ the &dtrace; kernel modules have been loaded using
+ <command>kldload dtraceall</command>, the system will
+ have support for the Korn shell. This
is needed as the &dtrace;Toolkit has several utilities written
- in <command>ksh</command>. Install the
- <package>shells/ksh93</package>. It is also
+ in <command>ksh</command>. Make sure that the
+ <package>shells/ksh93</package> package or port is installed.
+ It is also
possible to run these tools under
<package>shells/pdksh</package> or
<package>shells/mksh</package>.</para>
<para>Finally, obtain the current &dtrace;Toolkit.
- If you are running FreeBSD 10, you will find the &dtrace;Toolkit
+ FreeBSD 10 includes the &dtrace;Toolkit
in <filename>/usr/share/dtrace</filename>.
- Otherwise, you can install the &dtrace;Toolkit using the
- <package>sysutils/DTraceToolkit</package>
+ Otherwise, install the &dtrace;Toolkit using the
+ <package>sysutils/DTraceToolkit</package> package or
port.</para>
</sect1>
<sect1 xml:id="dtrace-using">
<title>Using &dtrace;</title>
- <para>Before making use of &dtrace; functionality, the &dtrace;
- device must exist. To load the device, issue the following
- command:</para>
-
- <screen>&prompt.root; <userinput>kldload dtraceall</userinput></screen>
-
- <para>&dtrace; support should now be available. To view all
+ <para>To view all
probes the administrator may now execute the following
command:</para>
@@ -255,14 +236,6 @@ options DDB_CTF</programlisting>
use <filename>/usr/bin/perl</filename> will need altered to
use <filename>/usr/local/bin/perl</filename>.</para>
- <important>
- <para>At this point it is prudent to remind the reader that
- &dtrace; support in &os; is <emphasis>incomplete</emphasis>
- and <emphasis>experimental</emphasis>. Many of these scripts
- will not work as they are either too &solaris;-specific or
- use probes which are unsupported at this time.</para>
- </important>
-
<para>At the time of this writing only two of the scripts of the
&dtrace; Toolkit are fully supported in &os;:
the <filename>hotkernel</filename>
More information about the svn-doc-all
mailing list