Date: Mon, 14 Apr 2014 18:39:13 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44555 - in head/en_US.ISO8859-1/books/handbook: config dtrace Message-ID: <201404141839.s3EIdDwI075758@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404141839.s3EIdDwI075758>