Kernel Support for HP OmniBooks, Pavilions, Toshiba Satellites,
                   Acer Aspire 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 as ODM.

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 or other I/O registers 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 is more types of firmware (only the tested models are
   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 1950
       Toshiba Satellite 1955
       Toshiba Satellite 3000
       Toshiba Satellite 3005
       Compal ACL00
       Compal ACL10
       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
       HP Pavilion XH545
    3. HP OmniBook 500
       HP Pavilion ZU1155
       HP Pavilion ZU1175
    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
       HP/Compaq nx9000
       HP/Compaq nx9010
       Acer Aspire 1350
    8. HP OmniBook 4150
       HP OmniBook 900B
    9. HP OmniBook XE2
   10. Fujitsu-Siemens Amilo D (CY23)

   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 and /proc/omnibook/version are 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 some XE3 GC style models there is scancode emulation for volume
    buttons on 2.4 series kernels, but it is disabled by default because
    of not all machines need it. For example volume buttons of
    HP Pavilion XH545 generate scancodes, so enable this feature if you
    really need it.

    To enable it use the command:

	echo 1 > /proc/omnibook/key_polling

    The command

	echo 0 > /proc/omnibook/key_polling

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

    Note: Polling function may cause slow down and packet loss on serial
          interfaces in certain configurations. If you experience this you
          may disable polling while you use the serial interface.
          Yes, polling is very expensive way and spin_locks during every
          poll is more expensive, but there is no other solution for volume
          key support without ACPI. If you use ACPI you may use acpid to
          support volume keys, because of pressing these keys causes ACPI
          events appear in /proc/acpi/events.

 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 work, even
    apm is enabled, but via this file you can monitor your battery
    independently from apm code.

    Current ACPI driver reports some bad value 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

	This is because the methods used for batteries in the DSDT do
	not give correct informations. If you want to fix it you may
	have to change methods in the DSDT.
	See http://www.intel.com/technology/iapc/acpi/bios_override.htm
	for details.

 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.

    Note: On XE3 GF style machines direct fan control works only if the CPU
          temperature is between fan on and fan off temperature (see below).

    The /proc/omnibook/fan_policy file provides information about fan control 
    policy of your machine. Currently it is available on XE3 GF style models
    because ot these machines have easily available hardware fan policy
    support. On other machines fan policy can be available via ACPI. To see
    the fan policy settings see the file /proc/omnibook/fan_policy:

	$ cat /proc/omnibook/fan_policy
	Fan off temperature:        60 C
	Fan on 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 on temperature:         If fan is off and the CPU temperature
                                reaches this value the fan turns on.
    Fan level n temperature:    Fan will be run at level n when CPU
                                temperature reaches this value. These are
                                informational values only expect the 7th
                                level. When CPU temperature reaches the 7th
                                value, the laptop (at least mine) turns off
                                so use it carefully.

    To set the fan policy write the proper values into the
    /proc/omnibook/fan_policy file. Each value must be greater than or
    equal to the prvious one. You do not have to write all values.
    For example you may set fan off temperature to 60 C, fan on 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) of omnibook module.

    Note: These default values are not the hardware defaults. You may get
          hardware defaults after resetting your machine (removing both
          AC power and battery).

    Note: If you prefer the direct fan control on XE3 GF style machines
          set the fan off temperature low and fan on temperature high and
          use /proc/omnibook/fan to control the fan directly.
          Warning: You may overheat your CPU.

 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 without apm support, and try to load omnibook
    module with APM emulation.

    Note: This works only if battery and AC adapter monitoring is supported
          on you machine.

 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.

    Note: Setting the LCD brightness on HP OmniBook XE3 GF via
          /proc/omnibook/lcd is working if you press one of the
          brightness control keys once after writing the value
          into /proc/omnibook/lcd. I'll try to fix it, but I have
          no idea about reason yet.

    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

    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

You may enable features above via the proper module parameters. See the 
output of

	modinfo omnibook

command.

Usually you have to be root to change anything via files in /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

Graphical frontends
-------------------
There are at least two graphical frontends for omnibook kernel module:

1. wmtemp from Ducrot Bruno <ducrot@poupinou.org> is a WindowMaker dockapp
   to monitor the CPU temperature and control the fan. It is available from
   http://sf.net/projects/omnibook.
2. komnibook from Guilherme Fortunato <guilherme@linksat.com.br> is a KDE
   frontend that would stay in the tray and display/set status information
   of the laptop. It is available from http://sf.net/projects/omnibook.

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 does not support ACPI 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 (in 2002):

> 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
