============================================ Linux-ready firmware developer kit: README ============================================ SECTIONS: 1. LFDK (Linux-ready Firmware Developer Kit) Overview 2. Design Goals 3. Implementation 4. Developer Docs & Resources 5. How to Contribute 6. Who are you? 7. Runtime dependencies 1. LFDK Overview ------------------- The Linux-ready Firmware Developer Kit is a tool to test how well Linux works together with the firmware (BIOS or EFI) of your machine. The main component of the kit is the biostest executable along with a suite of pluggin test cases. A bootable CD, which you can build in multiple ways. Or download from our official site: http://www.linuxfirmwarekit.org . When this CD boots, the Linux kernel starts and launches the test application. Note: we now support multiple kernel flavors, and you can choose which ones to test during boot-up. This application performs a set of automated tests on your machine and then reports the results for interactive inspection and saving. The test application also assists you in running some of our non-automated firmware tests. The idea is that you, as a firmware developer, validation team, kernel developer, or Linux user, use this CD to run the tests against your firmware and Linux kernel of choice. All code is distributed under the GNU Lesser General Public License v2.1. A copy of this license is contained in the COPYING file. This document gives a brief overview of the developer kit, including its design goals, implementation, and how to contribute. Within these sections, we also describe where to find more detailed information. 2. Design Goals ---------------- This project was created with the following design goals: * Ease of testing Linux without a high learning curve We wanted those with little or no Linux experience to easily gets results within 15 minutes, quickly and painlessly. * Low-noise, valuable feedback Valuable, thorough and decipherable test results with hardly any need for the user to manually do anything. * Simple to contribute For it to be simple for other developers to contribute and write their own tests for the kit. * support OSVs and system integrators with the integration of the tests into their own environments. We've gotten feedback from our users wish for an RPM install such to make it easier to add the tests into whatever environment they are running. 3. Implementation ------------------ The design and implementation of the kit are built upon these pillars: I. ONE DIR FOR EACH PLUGIN-TEST: Each plugin-test will have its own directory using a short, informative name. (e.g. 'fan' tests the fan, 'battery' tests the battery, etc.) II. MAKEFILE & PLUGIN-TEST EXECUTABLE: Each plugin-test has a Makefile where the result of 'make' can either be a standalone .exe or .sh, or a .so, using the same name as the directory and plugin-test. (e.g. 'battery.exe' or 'fan.exe', etc.) This resulting binary (and any other helper binaries) should be copied to the plugins/ directory in order to be run by the kit. III. PLUGIN-TEST DOCU & .INFO FILE: Each plugin-test will have a .info file with also the same name as the plugin-test (e.g. battery.info, fan.info). This file will reside in Documentation/TestsInfo/*.info and will be sym-linked in the directory of the plugin-test. The .info file will contain the description of the plugin-test with an explanation of all possible results (FAIL, WARN, PASS, INFO). IV. CUSTOMIZABILITY: The firmwarekit will be completely customizable so that users may add their own plugin-tests or kernels to the kit. Under LGPL v2.1 they will legally not need to open source any of their tests if they are using it in an internal environment that doesn't permit, although open sourcing and sharing their tests are very encouraged so we all can benifit. 4. Developer Docs & Resources ------------------------------ AUTHORS - who we are. BUILD - general on how to build and run the tests. COPYING - license GNU Lesser General Public License v2.1 README - you're there. _example/ - examples of plugins, see HOWTO_WritePluginTest for more. All documentation below is available under Documentation/ . Build.env - example build environment, list of packages and kernel version. HOWTO_CreateISO - create the bootable kit ISO. HOWTO_CustomizeISO - customize the kit to add or remove kernels in ISO. HOWTO_RunStandalone - build and run standalone tests on your current Linux distro. HOWTO_UbuntuBuildEnvironment - info on how to set up an Ubuntu build env. HOWTO_WritePluginTest - instructions on how to write your own plugin-test. QUICKSTART - a very quick guide to boot the CD and run the tests. USERGUIDE - LFDK complete user guide on how to run the kit, navigate through the test results, run interactive tests and hardware pokes. TestsInfo/ - list of .info files for all plugins (tests) with descriptions, results explanations and more. 5. How to Contribute --------------------- * Patches welcome! Our general mailing list for patches, discussions, announcements, etc. is right here: http://www.bughost.org/mailman/listinfo/firmwarekit-discuss * Share your test results at our test-results mailing list: http://www.bughost.org/mailman/listinfo/firmwarekit-results * Found a bug? http://www.bughost.org/firmwarekit/enter_bug.cgi * See HOWTO_WritePluginTest in our Documentation section. 6. Who are you? --------------- Check out AUTHORS file :) Contributer: Rolla Selbak (rolla.n.selbak@intel.com) 7. Runtime dependencies --------------------- For the RPM install to work on your custom distribution you need * slang (needs slang-dev to build) * newt (needs newt-dev and TCL to build) * dhclient (needed by ethernet test) * lscpi (needed by mtrr, pciresource tests) * dmidecode (needed by dmi test)