From owner-svn-doc-head@FreeBSD.ORG Mon Apr 14 19:48:31 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id F04257AE; Mon, 14 Apr 2014 19:48:31 +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 DB7F51356; Mon, 14 Apr 2014 19:48:31 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3EJmV09004770; Mon, 14 Apr 2014 19:48:31 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3EJmVDu004769; Mon, 14 Apr 2014 19:48:31 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404141948.s3EJmVDu004769@svn.freebsd.org> From: Dru Lavigne Date: Mon, 14 Apr 2014 19:48:31 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44556 - head/en_US.ISO8859-1/books/handbook/config X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 14 Apr 2014 19:48:32 -0000 Author: dru Date: Mon Apr 14 19:48:31 2014 New Revision: 44556 URL: http://svnweb.freebsd.org/changeset/doc/44556 Log: Editorial review of first 1/2 of ACPI chapter. Move how to submit a report subsection to after the troubleshooting sub-section. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/config/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 18:39:12 2014 (r44555) +++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Apr 14 19:48:31 2014 (r44556) @@ -2854,9 +2854,7 @@ kern.maxvnodes: 100000 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. + management of power levels. There are four major problems in APM. First, power management is done by the vendor-specific @@ -2881,15 +2879,15 @@ kern.maxvnodes: 100000 or one that can adapt well to the purpose of the machine. - The Plug and Play BIOS - (PNPBIOS) was unreliable in + The Plug and Play BIOS + (PNPBIOS) was unreliable in many situations. PNPBIOS is 16-bit technology, so the operating system has to use 16-bit emulation in order to interface with PNPBIOS methods. &os; provides an - APM driver for backwards compatibility with - older hardware. The driver is documented in - &man.apm.4;. + APM driver as APM should + still be used for systems manufactured at or before the year + 2000. The driver is documented in &man.apm.4;. ACPI @@ -2902,14 +2900,11 @@ kern.maxvnodes: 100000 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 + alliance of vendors to provide an 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.. + and flexibility to the operating system. This chapter demonstrates how to configure ACPI on &os;. It then offers some tips on @@ -2921,21 +2916,18 @@ kern.maxvnodes: 100000 Configuring <acronym>ACPI</acronym> - The &man.acpi.4; driver is loaded by default at start - up by &man.loader.8; and should - not be compiled into the kernel. The - reasoning is that modules are easier to work with and do not - require a kernel rebuild. This has the advantage of making - testing easier. Another reason is that starting - ACPI after a system has been brought up - often does not work well. If experiencing problems, - ACPI can be disabled altogether. This - driver should not and can not be unloaded because the system + In &os; the &man.acpi.4; driver is loaded by default at system + boot and should + not be compiled into the kernel. This + driver can not be unloaded after boot because the system bus uses it for various hardware interactions. - ACPI can be disabled by rebooting after + However, if the system is experiencing problems, + ACPI can be disabled altogether + by rebooting after setting hint.acpi.0.disabled="1" in /boot/loader.conf or by setting this - variable at the &man.loader.8; prompt. + variable at the loader prompt, as described in . ACPI and APM @@ -2945,146 +2937,26 @@ kern.maxvnodes: 100000 ACPI can be used to put the system into - a sleep mode with &man.acpiconf.8;, the - flag, and a 1-5 option. Most users + a sleep mode with acpiconf, the + flag, and a number from 1 to 5. Most users only need 1 (quick suspend to RAM) or 3 (suspend to RAM). Option 5 performs - a soft-off which is the same action as: + a soft-off which is the same as running halt -p. - &prompt.root; halt -p - - Other options are available via &man.sysctl.8;. Refer to + Other options are available using sysctl. Refer to &man.acpi.4; and &man.acpiconf.8; for more information. - - - Debugging &os; <acronym>ACPI</acronym> - - - - - Nate - Lawson - - Written by - - - - - - - Peter - Schultz - - With contributions from - - - - - Tom - Rhodes - - - - - - - ACPI - problems - - - ACPI is a fundamentally new way of - discovering devices, managing power usage, and providing - standardized access to various hardware previously managed by - the BIOS. Progress is being made toward - ACPI working on all systems, but bugs in some - motherboards' ACPI Machine - Language (AML) bytecode, - incompleteness in &os;'s kernel subsystems, and bugs in the - &intel; ACPI-CA interpreter continue to - appear. - - This section is intended to help users assist the &os; - ACPI maintainers in identifying the root - cause of problems and in debugging and developing a - solution. - - - Before submitting a problem, ensure the latest - BIOS version is installed and, if - available, the embedded controller firmware version. - - - When submitting a problem, send the following information - to - freebsd-acpi@FreeBSD.org: - - - - Description of the buggy behavior, including system - type and model and anything that causes the bug to appear. - Note as accurately as possible when the bug began - occurring if it is new. - - - - The output of &man.dmesg.8; after running - boot -v, including any error messages - generated by the bug. - - - - The &man.dmesg.8; output from boot - -v with ACPI disabled, - if disabling it helps to fix the problem. - - - - Output from sysctl hw.acpi. This - lists which features the system offers. - - - - The URL to a pasted version of the - ACPI Source - Language (ASL). Do - not send the - ASL directly to the list as it can be - very large. Generate a copy of the - ASL by running this command: - - &prompt.root; acpidump -dt > name-system.asl - - Substitute the login name for - name and manufacturer/model for - system. For example, use - njl-FooCo6000.asl. - - - - Most &os; developers watch &a.current;, but one should - submit problems to &a.acpi.name; to be sure it is seen. Be - patient when waiting for a response. If the bug is not - immediately apparent, submit a PR using - &man.send-pr.1;. When entering a PR, - include the same information as requested above. This helps - developers to track the problem and resolve it. Do not send a - PR without emailing &a.acpi.name; first as - it is likely that the problem has been reported before. - - - - Background - + + Common Problems ACPI ACPI is present in all modern computers that conform to the ia32 (x86), ia64 (Itanium), and amd64 - (AMD) architectures. The full standard has many features + (AMD) architectures. The full standard has many features including CPU performance management, power planes control, thermal zones, various battery systems, embedded controllers, and bus enumeration. Most systems @@ -3100,8 +2972,8 @@ kern.maxvnodes: 100000 in memory that specify things like the APIC map (used for SMP), config registers, and simple configuration values. Additionally, a bytecode table, - the Differentiated System Description - Table DSDT, specifies a + the Differentiated System Description + Table DSDT, specifies a tree-like name space of devices and methods. The ACPI driver must parse the fixed @@ -3116,10 +2988,6 @@ kern.maxvnodes: 100000 in src/sys/dev/acpica/Osd. Finally, drivers that implement various ACPI devices are found in src/sys/dev/acpica. - - - - Common Problems ACPI @@ -3129,7 +2997,9 @@ kern.maxvnodes: 100000 For ACPI to work correctly, all the parts have to work correctly. Here are some common problems, in order of frequency of appearance, and some possible - workarounds or fixes. + workarounds or fixes. If a fix does not resolve the issue, + refer to for instructions + on how to submit a bug report. Mouse Issues @@ -3137,9 +3007,7 @@ kern.maxvnodes: 100000 In some cases, resuming from a suspend operation will cause the mouse to fail. A known work around is to add hint.psm.0.flags="0x3000" to - /boot/loader.conf. If this does not - work, consider sending a bug report using - &man.send-pr.1;. + /boot/loader.conf. @@ -3148,18 +3016,18 @@ kern.maxvnodes: 100000 ACPI has three suspend to RAM (STR) states, S1-S3, and one suspend - to disk state (STD), called - S4. S5 is - soft off and is the normal state the system - is in when plugged in but not powered up. - S4 can be implemented in two separate - ways. S4BIOS is a - BIOS-assisted suspend to disk. + to disk state (STD), called + S4. STD can be implemented in two separate + ways. The S4BIOS is a + BIOS-assisted suspend to disk and S4OS is implemented - entirely by the operating system. + entirely by the operating system. The normal state the system + is in when plugged in but not powered up is + soft off (S5). + - Start by checking sysctl hw.acpi - for the suspend-related items. Here are the results for a + Use sysctl hw.acpi to check + for the suspend-related items. These example results are from a Thinkpad: hw.acpi.supported_sleep_state: S3 S4 S5 @@ -3167,11 +3035,11 @@ hw.acpi.s4bios: 0 Use acpiconf -s to test S3, - S4OS, and + S4, and S5. An of one - (1), indicates + (1) indicates S4BIOS support instead - of S4 OS. + of S4 operating system support. When testing suspend/resume, start with S1, if supported. This state is most @@ -3180,11 +3048,7 @@ hw.acpi.s4bios: 0 which is similar to S1. Next, try S3. This is the deepest STR state and requires a lot of driver - support to properly reinitialize the hardware. If there are - problems resuming, email &a.acpi.name;. However, the - problem may not be resolved quickly since due to the amount - of drivers and hardware that need more testing and - work. + support to properly reinitialize the hardware. A common problem with suspend/resume is that many device drivers do not save, restore, or reinitialize their @@ -3210,8 +3074,8 @@ hw.acpi.s4bios: 0 console, a Firewire port and cable for using &man.dcons.4;, and kernel debugging skills. - To help isolate the problem, remove as many drivers - from the kernel as possible. If it works, narrow down which + To help isolate the problem, unload as many drivers + as possible. If it works, narrow down which driver is the problem by loading drivers until it fails again. Typically, binary drivers like nvidia.ko, display drivers, and @@ -3257,7 +3121,7 @@ hw.acpi.s4bios: 0 how the BIOS configures interrupts before correctness of the APIC (MADT) table, and routing of the - System Control Interrupt + System Control Interrupt (SCI). @@ -3297,7 +3161,7 @@ hw.acpi.s4bios: 0 get a backtrace. Follow the advice for enabling options DDB and setting up a serial console in or setting - up a &man.dump.8; partition. To get a backtrace in + up a dump partition. To get a backtrace in DDB, use tr. When handwriting the backtrace, get at least the last five and the top five lines in the trace. @@ -3314,25 +3178,13 @@ hw.acpi.s4bios: 0 First, try setting hw.acpi.disable_on_poweroff="0" in - &man.loader.conf.5;. This keeps ACPI + /boot/loader. This keeps ACPI from disabling various events during the shutdown process. Some systems need this value set to 1 (the default) for the same reason. This usually fixes the problem of a system powering up spontaneously after a suspend or poweroff. - - - Other Problems - - For other problems with ACPI, such as - it not working with a docking station or devices not being - detected, email a description to &a.acpi.name;. Some - issues may be related to unfinished parts of the - ACPI subsystem which might take a while - to be implemented. Be patient and prepared to test - patches. - @@ -3567,5 +3419,123 @@ debug.acpi.level="ACPI_LV_ERROR" + + + + Debugging &os; <acronym>ACPI</acronym> + + + + + Nate + Lawson + + Written by + + + + + + + Peter + Schultz + + With contributions from + + + + + Tom + Rhodes + + + + + + + ACPI + problems + + + ACPI provides a method for + discovering devices, managing power usage, and providing + standardized access to various hardware previously managed by + the BIOS. Progress is being made toward + ACPI working on all systems, but bugs in some + motherboards' ACPI Machine + Language (AML) bytecode, + incompleteness in &os;'s kernel subsystems, and bugs in the + &intel; ACPI-CA interpreter continue to + appear. + + This section is intended to help users assist the &os; + ACPI maintainers in identifying the root + cause of problems and in debugging and developing a + solution. + + + Before submitting a problem, ensure the latest + BIOS version is installed and, if + available, the embedded controller firmware version. + + + When submitting a problem, send the following information + to + freebsd-acpi@FreeBSD.org: + + + + Description of the buggy behavior, including system + type and model and anything that causes the bug to appear. + Note as accurately as possible when the bug began + occurring if it is new. + + + + The output of &man.dmesg.8; after running + boot -v, including any error messages + generated by the bug. + + + + The &man.dmesg.8; output from boot + -v with ACPI disabled, + if disabling it helps to fix the problem. + + + + Output from sysctl hw.acpi. This + lists which features the system offers. + + + + The URL to a pasted version of the + ACPI Source + Language (ASL). Do + not send the + ASL directly to the list as it can be + very large. Generate a copy of the + ASL by running this command: + + &prompt.root; acpidump -dt > name-system.asl + + Substitute the login name for + name and manufacturer/model for + system. For example, use + njl-FooCo6000.asl. + + + + Most &os; developers watch &a.current;, but one should + submit problems to &a.acpi.name; to be sure it is seen. Be + patient when waiting for a response. If the bug is not + immediately apparent, submit a PR using + &man.send-pr.1;. When entering a PR, + include the same information as requested above. This helps + developers to track the problem and resolve it. Do not send a + PR without emailing &a.acpi.name; first as + it is likely that the problem has been reported before. + +