Kernel Support for HP OmniBooks, Pavilions, Toshiba Satellite 3000s,
             Toshiba Satellite 1110s and Compal ACL00
===================================================================

This package intended to provide Linux kernel support for HP OmniBook
and Pavilion machines. The state of this code is experimental but it
wants to be a framework to extend the Linux support for HP OmniBook
and Pavilion, Toshiba Satellite, Acer Aspire and Compal ACL00 laptops
manufactured by Compal Electronics, Inc.

There is a similar project for Toshiba Satellite laptops wich supports
some HP OmniBooks too at ftp://ftp.poupinou.org/tosh_3000/.

How does it work?
-----------------
   Some features of HP OmniBooks can be controlled via the keyboard control
   and data registers. Commands and parameters were discovered by Pavel
   Mihaylov.

   Some other features available via /proc/omnibook/* provided by the
   Embedded Controller of your laptop. Informations comes from DSDT ACPI
   table of HP OmniBook XE3 GF dissassembled by Ducrot Bruno and others or
   discovered by me.

   Note: You do not have to enable APM or ACPI to use this driver.

   All supported models seems to have same keyboard and embedded controller:
   National Semiconductor PC87570 Keyboard and ACPI Embedded Controller or
   compatible, but with different types of firmware.
   See http://www.national.com/pf/PC/PC87570.html for more info.

   It seems there are more types of firmware (only the tested models listed):
   1. HP OmniBook XE3 GF
      HP OmniBook XT1000
      HP Pavilion ZT1141
      HP Pavilion ZT1175
      HP Pavilion ZT1195
      Toshiba Satellite 1000
      Toshiba Satellite 1005
      Toshiba Satellite 1110
      Toshiba Satellite 1115
      Toshiba Satellite 1900
      Toshiba Satellite 1905
      Toshiba Satellite 3000
      Toshiba Satellite 3005
      Compal ACL00
      Acer Aspire 1406 LC
   2. HP OmniBook XE3 GC
      HP OmniBook XE3 GD
      HP OmniBook XE3 GE
      HP Pavilion N5290
      HP Pavilion N5415
      HP Pavilion N5430
      HP Pavilion N5441
   3. HP OmniBook 500
   4. HP OmniBook 510
   5. HP OmniBook 6000
   6. HP OmniBook 6100
   7. HP OmniBook xe4100
      HP OmniBook xe4400
      HP OmniBook xe4500
      HP OmniBook vt6200
      HP OmniBook xt6200
      HP Pavilion xt155
      HP Pavilion ze4125
   8. HP OmniBook 4150

   If your model is not listed above you may try to load the module. If it
   have same DMI identification strigs as a supported machine it may works
   out of the box. Please report it.
   Only the /proc/omnibook/dmi is working when you load the module on an
   unsupported machine.
   In this case you may load the module with ectype parameter to force using
   a certain EC firmware type or see how became you machine supported at the
   end of this documet.

What is working?
----------------
 1. Enabling OneTouch buttons. See README.OneTouch for details.
    You may enable or disable it via /proc/omnibook/onetouch.
    There is a power management handler for reenabling the buttons at resume
    if they were enabled previously.
    On some (XE3 GC style) models the volume buttons do not generate
    scancodes, so emulation is necessary.

 2. Console (LCD display) blanking if APM does not do it (e.g. using ACPI).
    It turns off the backlight of LCD display for more intensive power
    saving when your console is idle.
    You may enable or disable it via /proc/omnibook/blank.

 3. Battery status monitoring via /proc/omnibook/battery.

 4. Fan and fan policy support via /proc/omnibook/fan and
    /proc/omnibook/fan_policy.

 5. You may enable or disable touchpad via /proc/omnibook/touchpad.
    There is a power management handler for redisabling the touchpad
    at resume if it was disabled previously.

 6. Emulate /proc/apm battery status monitoring. On my HP OmniBook XE3 GF the
    APM subsystem unable to monitor the battery but there are many status
    monitoring application using /proc/apm to get info. So I disable APM and
    use this module and I'm happy :).
    Note: this is working only if you have AC adapter and battery status
    monitoring enabled (see ac and battery module parameters).

 7. AC Adapter status monitoring via /proc/omnibook/ac.

 8. Display status monitoring /proc/omnibook/display.

 9. LCD brightness setting and monitoring.

10. Docking station/port replicator support.

How to use?
-----------
 1. The OneTouch buttons are enabled by default by this module.
    To disable it use the command:

	echo 0 > /proc/omnibook/onetouch

    The command

	echo 1 > /proc/omnibook/onetouch

    enables OneTouch buttons.

    On XE3 GC sytel models the scancode emulation for volume buttons is
    enabled by default.
    To disable it use the command:

	echo 0 > /proc/omnibook/key_polling

    The command

	echo 1 > /proc/omnibook/key_polling

    enables the polling of the volume buttons and emulating scancodes for
    them.


 2. Console (LCD display) blanking is enabled by this module on machines that
    support it. It only enabled if another blanking solution
    (e.g. CONFIG_APM_DISPLAY_BLANK) is not used.
    To disable this behavior use command:

	echo 0 > /proc/omnibook/blank

    To enable this behavior use command:

	echo 1 > /proc/omnibook/blank

 3. To see the battery status use

	cat /proc/omnibook/battery

    command. It produce similar output to that you can see below.

	Battery:                      0
	Type:                    Li-Ion
	Serial Number:            20722
	Present Voltage:          12668 mV
	Design Voltage:           11100 mV
	Remaining Capacity:        4859 mAh
	Last Full Capacity:        4933 mAh
	Design Capacity:           5400 mAh
	Gauge:                       98 %
	Status:                charging

    On some models (e.g. HP OmniBook XE3 GF) /proc/apm does not works, even
    is apm is enabled, but via this file you can monitor your battery
    independently from apm code.

    Current ACPI driver reports some bad values about battery at least on my
    machine:

	$cat /proc/acpi/battery/BAT1/info
	present:                 yes
	design capacity:         5400 mAh
	last full capacity:      5400 mAh
	battery technology:      rechargeable
	design voltage:          8191 mV
	design capacity warning: 540 mAh
	design capacity low:     162 mAh
	capacity granularity 1:  264 mAh
	capacity granularity 2:  3780 mAh
	model number:            LIP9071
	serial number:
	battery type:            LiON
	OEM info:                HP


 4. The /proc/omnibook/fan file provides information about fan status:

	$ cat /proc/omnibook/fan
	Fan is off

    or

	$ cat /proc/omnibook/fan
	Fan is on

    On certain machines you may turn on the fan by

	echo 1 > /proc/omnibook/fan

    command and turn off by issuing

	echo 0 > /proc/omnibook/fan

    command.

    On XE3 GF style machines, fan on works only if the CPU temperature is
    over fan off temperature (see below).

    The /proc/omnibook/fan_policy file provides information about fan control 
    policy of your machine (currently on XE3 GF style models):

	$ cat /proc/omnibook/fan_policy
	Fan off temperature:        60 C
	Fan level 1 temperature:    75 C
	Fan level 2 temperature:    85 C
	Fan level 3 temperature:    90 C
	Fan level 4 temperature:    95 C
	Fan level 5 temperature:    95 C
	Fan level 6 temperature:    95 C
	Fan level 7 temperature:    95 C
	Minimal temperature to set: 25 C
	Maximal temperature to set: 95 C

    The important values:

    Fan off temperature:        If fan is cooling the CPU and reaches this
                                temperature it will be switched off.
    Fan level n temperature:    Fan will be run at level n when CPU
                                temperature reaches this value.

    For example yo may set fan off temperature to 60 C, fan level 1
    temperature to 70 C and fan level 2 temperature to 80 C by

	echo 60 70 80 > /proc/omnibook/fan_policy

    command.
    A zero value (echo 0 > /proc/omnibook/fan_policy) sets the default
    values (60 75 85 90 95 95 95 95).

    Note: not all models supports all fan levels. Usually fan off, level 1
    and possibly level 2 are used. You may use them as warning levels.

    When CPU temperature reaches the 7th value, the laptop (at least mine)
    turns off so be careful with it.

 5. The touchpad is enabled by default by the BIOS.
    To disable it use the command:

	echo 0 > /proc/omnibook/touchpad

    The command

	echo 1 > /proc/omnibook/touchpad

    enables the touchpad.

 6. The /proc/apm emulation is disabled by default on all machines. You have
    to enable it explicit way by module parameter apmemu. To enable it use:

	insmod omnibook apmemu=1

    You can enable it by /etc/modules.conf with the following entry:

	options omnibook apmemu=1

    If your kernel have APM support, but the /proc/apm reports buggy values, you
    may boot your kernel with apm=broken_psr parameter, and try to load omnibook
    module with APM emulation.

 7. To see the AC adapter status use

	cat /proc/omnibook/ac

    command. It produce similar output to that you can see below.

	$ cat /proc/omnibook/ac
	AC on-line

    Or if you are on battery power:

	$ cat /proc/omnibook/ac
	AC off-line

 8. To see the display status use

	cat /proc/omnibook/display

    command. It produce similar output to that you can see below.

	$ cat /proc/omnibook/display
	External display is not present

    Or if you have external monitor installed:

	$ cat /proc/omnibook/display
	External display is present

 9. To see the LCD brightness use

	cat /proc/omnibook/lcd

    command. It produce similar output to that you can see below.

	$ cat /proc/omnibook/lcd
	LCD brightness: 7

    To set it use similar command to that you can see below.

	echo 10 > /proc/omnibook/lcd

    The value of LCD brightness must be betwenn 0 and 10.

    To turn off the LCD backlight use

	echo off > /proc/omnibook/lcd

    To turn it back on use

	echo on > /proc/omnibook/lcd

    This is useful if you have an X server, such as the ATI Radeon,
    that does not know how to turn off the LCD backlight.  Use a
    long-running perl script which monitors xscreensaver activity
    such as the one below:

	open(XS,"/usr/X11R6/bin/xscreensaver-command -watch|") or die;
	while(<XS>) {
	   if(/^BLANK/i) {
	      system("echo off > /proc/omnibook/lcd");
	   } elsif(/^UNBLANK/i) {
	      system("echo on > /proc/omnibook/lcd");
	   }
	}

	Note: You have to enable users to set values in /proc/omnibook
              (See the user parameter below).

10. To check that your laptop is docked in a docking station or port
    replicator use

	cat /proc/omnibook/dock

    command. It produce similar output to that you can see below.

	$ cat /proc/omnibook/dock
	Laptop is undocked

    or

	$ cat /proc/omnibook/dock
	Laptop is docked

    On certain models you can undock automatically the machine by issuing
    the:

	echo 0 > /proc/omnibook/blank

    command. (It don't always work. I don't know why.)

    Note: docking station support is disabled by default on all machines.
    You have to enable it explicit way by module parameter dock. To enable
    it use:

        insmod omnibook dock=1

    You can enable it by /etc/modules.conf with the following entry:

	options omnibook dock=1

Usually you have to be root to change anything via /proc/omnibook. If you
want to do it as ordinary user, and you trust the other (e.g. networked)
users or you are the only user of the laptop you may load the module with
the parameter user to enable non-root accounts to set omnibook paremeters
as follows:

	insmod omnibook user=1

You can enable users to set parameters by /etc/modules.conf with the
following entry:

	options omnibook user=1

How can your laptop be supported?
---------------------------------
If your model is unsupported and you want it to be supported I need four
things:

1. Test your machine with Pavel's omke.pl and report the result. You
   should include that a feature works or not and details if any
   (eg. OneTouch keycodes in hex as appears in syslog after enabling
    them by omke.pl etc.).

2. Force the module to load with an embedded controller firmware type
   detailed above. For example if you want to test that your machine
   is an XE3GF style model, use the following command:

	insmod omnibook ectype=1

   then test the features are working properly, and send me the result.

   Warning!!! Forced load on an unsupported machine may cause
   unpredictable result. You have been warned...

3. Send me DMI strings of your machine (/proc/omnibook/dmi after
   loading omnibook module on any machine).

4. If possible send me the DSDT of your machine. If your kernel is 
   configured for ACPI you can found it at /proc/acpi/dsdt. Use the
   following command to get the DSDT AML file.

	cat /proc/acpi/dsdt > my_model_name.aml

   If your kernel do not support ACPI you you can get DSDT by pmtools
   can be found on Intel's developer site at
   http://www.intel.com/technology/IAPC/acpi/downloads.htm.
   Compile it and issue command similar to below to create the DSDT AML
   file.

	acpidmp DSDT > my_model_name.aml

   Please send me the AML file. Note: it is binary file.

This code was written without any documentation from HP or Compal so it
is provided as is without any warranty.

Contributions, bug reports and text corrections are welcome.

If you experience any problems after using this module try to reboot your
computer. If it does not help (eg. the laptop reboots in edless loop) turn
off the machine and remove the battery and the AC power cord for some
minutes. It it does not help too, remove the battery, plug in the AC power
cord, turn on the machine and unplug the AC power cord. It will reset your
laptop.

Unfortunately the official HP technical support refusing to share any
information with similar messages:

> Thank you for contacting Hewlett Packard laptop email support.
> 
> I'm sorry, but I won't be able to help you with that. HP does not
> recommend or support the installation of any version of Linux on any of
> our notebook products.

Compal Electronics, Inc. does not response to information requests at all.

Meanwhile (in 2002) Compaq and HP merged and as I know Compaq will the
supplier of the new laptop models in the merged company.

For more information you can see the OmniBook mailing list at
http://zurich.ai.mit.edu/mailman/listinfo/omnibook

You can find actual version of this code at
http://sourceforge.net/projects/omke
