Developing ACPI for Linux - March 27, 2007 ------------------------------------------ Len Brown <lenb@xxxxxxxxxx> (Intel Open Source Technology Center) This is how you can be most effective improving Linux ACPI support. Latest version of this file --------------------------- http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/README.ACPI Linux/ACPI home page -------------------- http://acpi.sourceforge.net/ Mailing Lists ------------- Inventory of lists: http://acpi.sourceforge.net/mailinglists.html The main list is linux-acpi@xxxxxxxxxxxxxxxx Subscribe here: http://vger.kernel.org/vger-lists.html#linux-acpi Note this list server has a 100KB message limit size. If you need to post something big, attaching it to a bugzilla entry (below) is usually the way to go. Which e-mail address to use? ---------------------------- For issues, discussion, RFC's, debugging etc: To: linux-acpi@xxxxxxxxxxxxxxx To request an ACPI patch be applied to Linux: To: lenb@xxxxxxxxxx Cc: linux-acpi@xxxxxxxxxxxxxxx Feedback to (only) Intel on Intel's ACPICA, or ACPI-related issues with NDA pre-production systems: To: acpi@xxxxxxxxxxxxxxx Len Brown is on both of these lists, and he also sees traffic to LKML, cpufreq, pci, and ia64 lists when the word ACPI appears in it. Note that Len signs-off using "len.brown@xxxxxxxxx" to make it clear that he is employed by Intel. While that address is functional, lenb@xxxxxxxxxx is preferred for all public Linux work. asus_acpi or asus-laptop specific e-mail: to: acpi4asus-user@xxxxxxxxxxxxxxxxxxxxx ibm_acpi specific e-mail: ibm-acpi-devel@xxxxxxxxxxxxxxxxxxxxx Bugzilla -------- The Linux/ACPI community makes active use of bugzilla. http://bugzilla.kernel.org/enter_bug.cgi?product=ACPI Note that this database is for kernel.org kernels only. If an issue is specific to a distribution, it should be filed in their database. If a sighting appears in both, please cross reference it using a complete URL. In both cases, please cc: acpi-bugzilla@xxxxxxxxxxxxxxxxxxxxx on the bug report. You can subscribe to this list to see all ACPI bugzilla updates: https://lists.sourceforge.net/lists/listinfo/acpi-bugzilla Note that this list is intended for bugzilla machine-generated messages only. If the distribution bug report is private due to being on pre-production hardware and you want Intel's ACPI team to know about it, then cc: acpi@xxxxxxxxxxxxxxx Sometimes you'll see check-in comments including reference to small bugzilla numbers, eg. (BZ 123), these refer to a bugzilla database inside Intel where ACPICA issues are tracked that don't apply directly to the Linux kernel and thus would not fit within the charter of bugzilla.kernel.org. While discussion-oriented issues are best dealt with on the list, bugzilla has two useful properties: 1. you can attach a whole bunch of stuff there without irritating everybody on the list -- including items > 100KB. 2. bugzilla never forgets -- so your issue will not get lost in the shuffle of e-mail overload. Sometimes it works well to file the supporting debug output for your issue in bugzilla and then refer to it on the linux-acpi@xxxxxxxxxxxxxxx list. Please be sure to answer these questions when you submit the bug, so they don't have to be asked later: 0. Exactly what kernel version does this bug appear in? 1. Does it still appear in the latest version? 2. Is this a new problem (a regression) or has this problem always existed in every version of Linux tested? 3. If a regression, what is the latest version of the kernel.org kernel where it does not happen? If you have a git tree, can you isolate the regression to a particular commit using git-bisect? 4. For the latest working, and for the failing kernel please _attach_ (do not paste) the complete output from dmesg -s64000 or serial console capture with "debug" on cmdline, if possible. 5. If it is an interrupt-related problem, please paste a copy of /proc/interrupts showing both the success and failure case, if possible. Also include the full output from lspci -vv. 6. Please attach the complete, unprocessed output from acpidump. acpidump is available in /usr/sbin, or in the latest PMtools here: http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils/ Note that very old versions of this tool were called "acpidmp", and if that is on hand and it works, then that is okay too. 7. If this turns out to be a platform-specific issue where we may have to blacklist the machine to enable a workaround, please include the output from dmidecode. Linux/ACPI Patch Flow --------------------- 1. The community develops, reviews, and tests patches 2. Len Brown, the Linux/ACPI Maintainer, checks them into the "acpi-test" tree (below) 3. Andrew Morton incorporates acpi-test into mm as git-acpi.patch 4. Len moves mature patches from acpi-test to a release branch, and requests Linus Torvalds pull them into the upstream kernel. 5. Distributors re-base their products onto Linus' kernel Linux Release Cycle ------------------- Len aims to integrate all ACPI patches for each release during the 1st week of Linus' 2-week "integration window". This refers to period between when Linus releases 2.6.X and 2.6.X+1-rc1. For patches to go upstream in this window, they should have already been pushed into Len's linux-acpi tree and appeared in several of Andrew's -mm releases. Patches that miss this window must wait 6 weeks for the next window to open up. The period after X+1-rc1 and X+1 release is intended for fixing any regressions, and for low-risk critical bug fixes. Sending Patches --------------- Read and follow Documentation/SubmittingPatches Proposed patches to the Linux/ACPI kernel sub-system should be e-mailed to linux-acpi@xxxxxxxxxxxxxxx for review, comment, and testing by the community. Many patches also are cc'd to linux-kernel@xxxxxxxxxxxxxxxx If the patch touches code outside drivers/acpi, including LKML is mandatory. It is important to describe your expectations of the patch in the e-mail. If it is an experiment, or a debug patch, please say so. If you think it is well tested, broadly reviewed and ready to integrate into the upstream kernel, say that using the words "please apply", adding lenb@xxxxxxxxxx the "to: list" to make sure he sees your request. Note that Len prefers patches in plain text, but if you need to use attachments to deal with your mail client, that is okay too. Len also takes patches directly from bugzilla entries. Indeed, he tries to give priority to bugzilla fixes because bugzilla does such a good job remembering the details of the issue, and the people involved have taken the trouble to carefully enter the data in bugzilla. If you send a patch as an attachment, or attach it to bugzilla, it is helpful if you format the patch according to SubmittingPatches, ie. include a From:, Subject: and check-in comments before the patch body. ACPICA ------ Len also integrates updates from ACPICA, the "ACPI Component Architecture" -- the core interpreter that Intel develops for the benefit of all ACPI operating systems. (okay, all but Windows -- MS uses their own interpreter) Intel publishes ACPICA under a dual source license so that FreeBSD etc. can use it w/o GPL tainting. Linux gets huge benefits from sharing this core, and so preventing divergence between Linux and the shared ACPICA code is why Len hates to accept GPL patches to some files. Note that the ACPICA files are the ones in the sub-directories under drivers/acpi/* plus a bunch of include/acpi/ headers. All the other kernel files in drivers/acpi/* and elsewhere are straight GPL -- as indicated in their header copyright comments. git --- Len follows Tony Luck's method of using GIT branches, documented in git/Documentation/howto/using-topic-branches.txt The latest patches intended for Linus are here: git://git.kernel.org/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git release The latest patches intended for community testing are here: git://git.kernel.org/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git test Andrew Morton periodically pulls the test branch and creates a consolidated git-acpi.patch and applies it to his mm release. git://git.kernel.org/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git acpica Is a topic-specific branch containing the latest ACPICA interpreter. It will get pulled into the test branch above when ready. There may be other topic-specific branches from time to time. Fetching code via git is the easiest way to stay up to date, so get git and get going: git pull git://git.kernel.org/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git test Git startup instructions: http://linux.yyz.us/git-howto.html Beware that Len takes the liberty of occasionally re-writing the history of the test branch. So you may have conflicts if you re-pull into an "untouched" repo. Sorry about that. This is because 1. Andrew doesn't care about history, he makes it into 1 patch anyway. 2. Linux wants "clean history" 3. Len wants Linus to get exactly what was tested, merges and all. So beware if you base a git tree on the acpi test branch. If you do, it means Len will unlikely be able to pull your tree. It is generally better to base your work off of Linus' tree, when possible. Len will generally have to apply your work vs. Linus' tree anyway. patches ------- ftp://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/release includes patches from the Linux/ACPI git release branch. Len publishes these when he sends a pull request to Linus. If Linus doesn't pull for a while, this patch tells you what is in the queue. As soon as Linus pulls, however, this patch becomes a duplicate of what is in Linus' tree and will thus no longer apply. The patches are named like so: acpi-release-20050902-2.6.15-rc5.diff.gz was created on the "release" branch, some time after 2.6.15-rc5, and includes ACPICA up through 20050902. ftp://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/patches/test includes patches from the Linux/ACPI test branch, as well as other topic branches such as acpica: acpi-test-20050916-2.6.15-rc5.diff.gz acpi-acpica-20051202-2.6.15-rc5.diff.gz Len rarely publishes individual test patches here, since they can now be pulled from the GUI using gitweb: http://www.kernel.org/git/?p=linux/kernel/git/lenb/linux-acpi-2.6.git patch signing ------------- files on ftp.kernel.org compressed and signed per http://www.kernel.org/signature.html If you'd like to verify the signature, import key by: gpg --keyserver wwwkeys.pgp.net --recv-keys 0x517D0F0E verify integrity by: gpg --verify <sigfile> <signed-file> you can skip <signed-file> if it is in the same directory as <sigfile>. applying patches ---------------- Both Test and Release patches have a header at the top of the patch including the commit comments to describe what is included in the patch. Note you can test if a patch will apply cleanly before you apply it for real: $ cd my-src/linux/ To test $ patch --dry-run -Np1 < acpi.patch For real: $ patch -Np1 < acpi.patch Where do I get acpidump for capturing my systems ACPI tables? ------------------------------------------------------------- Previously spelled acpidmp -- it is included in most distros. If not, you can get the latest version from the latest pmtools package here: http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils/ See the README in the package for how to use it. Where do I get iasl for dis-assembling and compiling tables? ------------------------------------------------------------ http://www.intel.com/technology/iapc/acpi/downloads.htm Note that "iasl -d" can now not only dis-assemble a DSDT and SSDT, but also most other ACPI table images. How to Build a custom DSDT into the kernel ------------------------------------------ Get original DSDT: # cp /proc/acpi/dsdt DSDT or # acpidump > acpidump.out $ acpixtract DSDT acpidump > DSDT Disassemble it $ iasl -d DSDT Make your changes: $ vi DSDT.dsl Build it: $ iasl -tc DSDT.dsl Put it where the kernel build can include it: $ cp DSDT.hex $SRC/include/ Add this to the kernel .config: CONFIG_STANDALONE=n CONFIG_ACPI_CUSTOM_DSDT=y CONFIG_ACPI_CUSTOM_DSDT_FILE="DSDT.hex" Make the kernel and off you go! You should see in dmesg: Table [DSDT] replaced by host OS Note that with CONFIG_ACPI_DEBUG=y then ASL stores to the special object "Debug" will come out in the dmesg. eg Store("hello world!", Debug) Store(Local0, Debug) [ACPI Debug] String: [0x0C] "hello world!" [ACPI Debug] Integer: 0x00000042 ACPI: Looking for DSDT ... not found! ------------------------------------- This is a message from a patch that SuSE and Ubuntu integrate into their distributions so that you can over-ride the DSDT without re-compiling the kernel. If you don't like the message, contact your distributor. Len will not apply that patch upstream because: 1. Modified firmware has no place on supported systems. 2. If Windows can handle un-modified firmware, Linux should too. 3. Linux distributors can not support systems running modified firmware. 4. If somebody is unable to re-build the kernel, then they have no business running modified platform firmware. Yes, there is at least one person who wants to run the same kernel on multiple machines all running different modified DSDTs -- they can run SuSE. Yes, SuSE can use this technique to debug issues without requiring the customer to re-build the kernel. However, neither case justifies this capability upstream. - To unsubscribe from this list: send the line "unsubscribe linux-acpi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
