Developing ACPI for Linux - FAQ ------------------------------- Len Brown <lenb@xxxxxxxxxx> (Intel Open Source Technology Center) February 8, 2007 This file attempts to document how you can be most effective in developing and improving Linux ACPI support. Latest version: 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 the 100KB message limit size and bugzilla availability below. 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 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 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. 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. Please be encouraged to file the supporting debug output for your issue in bugzilla and refer to it on the linux-acpi@xxxxxxxxxxxxxxx list. Patch Flow ---------- 1. The community develops, reviews, and tests patches 2. Len checks them into the "acpi-test" tree 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 pull it into the upstream kernel. 5. Distributors re-base their products onto Linus' kernel If you send a patch, 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, that 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. 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? -------------------------------------------------------------:w 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. Building 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 he believes: 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. - 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
