From owner-svn-doc-all@FreeBSD.ORG Mon Apr 14 18:39:13 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 816BE776; Mon, 14 Apr 2014 18:39:13 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 6CC1A1AB1; Mon, 14 Apr 2014 18:39:13 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3EIdDsp075760; Mon, 14 Apr 2014 18:39:13 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3EIdDwI075758; Mon, 14 Apr 2014 18:39:13 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404141839.s3EIdDwI075758@svn.freebsd.org> From: Dru Lavigne Date: Mon, 14 Apr 2014 18:39:13 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 14 Apr 2014 18:39:13 -0000 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 It is important to utilize hardware resources in an - efficient manner. Before the Advanced Configuration and Power - Interface (ACPI) 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 BIOS and the user had less - control and visibility into the power management settings. Some - limited configurability was available via Advanced - Power Management (APM). Power - and resource management allows the operating system to monitor - system limits and to possibly provide an alert if the system - temperature increases unexpectedly. - - This section provides comprehensive information about - ACPI. References will be provided for - further reading. - - - What Is ACPI? - - - ACPI - - - - APM - - - ACPI 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 Operating System-directed configuration - and Power Management 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 - ACPI. ACPI is the - direct successor to APM. - - - - Shortcomings of Advanced Power Management - - The APM facility controls the power - usage of a system based on its activity. The - APM BIOS is supplied - by the vendor and is specific to the hardware platform. An - APM driver in the operating system - mediates access to the APM - Software Interface, which allows management of - power levels. APM should still be used - for systems manufactured at or before the year 2000. + 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 + (APM) facility. APM + 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 BIOS and the + user had limited configurability and visibility into the power + management settings. The APM + BIOS is supplied by the vendor and is + specific to the hardware platform. An APM + driver in the operating system mediates access to the + APM Software Interface, which allows + management of power levels. APM should still + be used for systems manufactured at or before the year + 2000. There are four major problems in APM. First, power management is done by the vendor-specific @@ -2918,11 +2886,37 @@ kern.maxvnodes: 100000 many situations. PNPBIOS is 16-bit technology, so the operating system has to use 16-bit emulation in order to interface with - PNPBIOS methods. - - The &os; APM driver is documented in + PNPBIOS methods. &os; provides an + APM driver for backwards compatibility with + older hardware. The driver is documented in &man.apm.4;. - + + + ACPI + + + + APM + + + The successor to APM is the Advanced + Configuration and Power Interface (ACPI). + ACPI 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 Operating System-directed configuration + and Power Management 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 + ACPI.. + + This chapter demonstrates how to configure + ACPI on &os;. It then offers some tips on + how to debug ACPI and how to submit a + problem report containing debugging information so that + developers can diagnosis and fix ACPI + issues. Configuring <acronym>ACPI</acronym> @@ -2963,11 +2957,10 @@ kern.maxvnodes: 100000 Other options are available via &man.sysctl.8;. Refer to &man.acpi.4; and &man.acpiconf.8; for more information. - - + - Using and Debugging &os; <acronym>ACPI</acronym> + Debugging &os; <acronym>ACPI</acronym> @@ -3018,9 +3011,6 @@ kern.maxvnodes: 100000 cause of problems and in debugging and developing a solution. - - Submitting Debugging Information - Before submitting a problem, ensure the latest BIOS 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. &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. + 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. &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. + + 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 pid provider, and to insert static probes + into userland programs for later tracing. Some ports, such as + databases/postgres-server and + lang/php5 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. After reading this chapter, you will know: @@ -72,12 +84,6 @@ that might make this chapter too large. - Be familiar with - the basics of kernel configuration/compilation - (). - - - Have some familiarity with security and how it pertains to &os; (). @@ -87,18 +93,6 @@ that might make this chapter too large. (). - - - - 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. - @@ -106,9 +100,15 @@ that might make this chapter too large. 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. + 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: + + &prompt.root; kldload dtraceall + + Beginning with &os; 10.0-RELEASE, the modules are + automatically loaded when dtrace is + run. &os; uses the DDB_CTF kernel option to enable support for loading CTF @@ -127,7 +127,14 @@ that might make this chapter too large. Some different providers exist for &os; than for &solaris;. Most notable is the dtmalloc provider, which allows tracing malloc() by type in the - &os; kernel. + &os; kernel. Some of the providers found in &solaris;, such as + cpc and mib, 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, D scripts + written on &solaris; may or may not work unmodified on &os;, and + vice versa. Due to security differences, only root may use &dtrace; on &os;. @@ -151,78 +158,52 @@ that might make this chapter too large. Enabling &dtrace; Support - To enable support for &dtrace;, add the following lines to - the kernel configuration file: + In &os; 9.2 and 10.0, &dtrace; support is built into the + GENERIC 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 . options KDTRACE_HOOKS options DDB_CTF - Users of the AMD64 architecture will want to add the - following line to their kernel configuration file: + Users of the AMD64 architecture should also add this + line: options KDTRACE_FRAME - This option provides support for the - FBT feature. &dtrace; will work without - this option; however, there will be limited support for + This option provides support for + FBT. While &dtrace; will work without + this option, there will be limited support for function boundary tracing. - All sources must be rebuilt and installed with - CTF options. - - - Starting from 10.0, the following steps are not needed any - more as the WITH_CTF option is included in - the GENERIC kernel configuration. - - - To accomplish this task, rebuild the &os; sources - using: - - - - &prompt.root; cd /usr/src - -&prompt.root; make WITH_CTF=1 kernel - - - - The system will need to be restarted. - - After rebooting and allowing the new kernel to be loaded - into memory, support for the Korn shell should be added. This + Once the &os; system has rebooted into the new kernel, or + the &dtrace; kernel modules have been loaded using + kldload dtraceall, the system will + have support for the Korn shell. This is needed as the &dtrace;Toolkit has several utilities written - in ksh. Install the - shells/ksh93. It is also + in ksh. Make sure that the + shells/ksh93 package or port is installed. + It is also possible to run these tools under shells/pdksh or shells/mksh. 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 /usr/share/dtrace. - Otherwise, you can install the &dtrace;Toolkit using the - sysutils/DTraceToolkit + Otherwise, install the &dtrace;Toolkit using the + sysutils/DTraceToolkit package or port. Using &dtrace; - Before making use of &dtrace; functionality, the &dtrace; - device must exist. To load the device, issue the following - command: - - &prompt.root; kldload dtraceall - - &dtrace; support should now be available. To view all + To view all probes the administrator may now execute the following command: @@ -255,14 +236,6 @@ options DDB_CTF use /usr/bin/perl will need altered to use /usr/local/bin/perl. - - At this point it is prudent to remind the reader that - &dtrace; support in &os; is incomplete - and experimental. Many of these scripts - will not work as they are either too &solaris;-specific or - use probes which are unsupported at this time. - - At the time of this writing only two of the scripts of the &dtrace; Toolkit are fully supported in &os;: the hotkernel