Documentation/tp_smapi.txt

   1 tp_smapi version 0.40
   2 IBM ThinkPad hardware functions driver
   3
   4 Author:  Shem Multinymous <multinymous@gmail.com>
   5 Project: http://sourceforge.net/projects/tpctl
   6 Wiki:    http://thinkwiki.org/wiki/tp_smapi
   7 List:    linux-thinkpad@linux-thinkpad.org
   8          (http://mailman.linux-thinkpad.org/mailman/listinfo/linux-thinkpad)
   9
  10 Description
  11 -----------
  12
  13 ThinkPad laptops include a proprietary interface called SMAPI BIOS
  14 (System Management Application Program Interface) which provides some
  15 hardware control functionality that is not accessible by other means.
  16
  17 This driver exposes some features of the SMAPI BIOS through a sysfs
  18 interface. It is suitable for newer models, on which SMAPI is invoked
  19 through IO port writes. Older models use a different SMAPI interface;
  20 for those, try the "thinkpad" module from the "tpctl" package.
  21
  22 WARNING:
  23 This driver uses undocumented features and direct hardware access.
  24 It thus cannot be guaranteed to work, and may cause arbitrary damage
  25 (especially on models it wasn't tested on).
  26
  27
  28 Module parameters
  29 -----------------
  30
  31 thinkpad_ec module:
  32   force_io=1 lets thinkpad_ec load on some recent ThinkPad models
  33   (e.g., T400 and T500) whose BIOS's ACPI DSDT reserves the ports we need.
  34 tp_smapi module:
  35   debug=1    enables verbose dmesg output.
  36
  37
  38 Usage
  39 -----
  40
  41 Control of battery charging thresholds (in percents of current full charge
  42 capacity):
  43
  44 # echo 40 > /sys/devices/platform/smapi/BAT0/start_charge_thresh
  45 # echo 70 > /sys/devices/platform/smapi/BAT0/stop_charge_thresh
  46 # cat /sys/devices/platform/smapi/BAT0/*_charge_thresh
  47
  48     (This is useful since Li-Ion batteries wear out much faster at very
  49      high or low charge levels. The driver will also keeps the thresholds
  50      across suspend-to-disk with AC disconnected; this isn't done
  51      automatically by the hardware.)
  52
  53 Inhibiting battery charging for 17 minutes (overrides thresholds):
  54
  55 # echo 17 > /sys/devices/platform/smapi/BAT0/inhibit_charge_minutes
  56 # echo 0  > /sys/devices/platform/smapi/BAT0/inhibit_charge_minutes  # stop
  57 # cat /sys/devices/platform/smapi/BAT0/inhibit_charge_minutes
  58
  59     (This can be used to control which battery is charged when using an
  60      Ultrabay battery.)
  61
  62 Forcing battery discharging even if AC power available:
  63
  64 # echo 1 > /sys/devices/platform/smapi/BAT0/force_discharge  # start discharge
  65 # echo 0 > /sys/devices/platform/smapi/BAT0/force_discharge  # stop discharge
  66 # cat /sys/devices/platform/smapi/BAT0/force_discharge
  67
  68     (When AC is connected, forced discharging will automatically stop
  69      when battery is fully depleted -- this is useful for calibration.
  70      Also, this attribute can be used to control which battery is discharged
  71      when both a system battery and an Ultrabay battery are connected.)
  72
  73 Misc read-only battery status attributes (see note about HDAPS below):
  74
  75 /sys/devices/platform/smapi/BAT0/installed   # 0 or 1
  76 /sys/devices/platform/smapi/BAT0/state       # idle/charging/discharging
  77 /sys/devices/platform/smapi/BAT0/cycle_count # integer counter
  78 /sys/devices/platform/smapi/BAT0/current_now # instantaneous current
  79 /sys/devices/platform/smapi/BAT0/current_avg # last minute average
  80 /sys/devices/platform/smapi/BAT0/power_now   # instantaneous power
  81 /sys/devices/platform/smapi/BAT0/power_avg   # last minute average
  82 /sys/devices/platform/smapi/BAT0/last_full_capacity         # in mWh
  83 /sys/devices/platform/smapi/BAT0/remaining_percent          # remaining percent of energy (set by calibration)
  84 /sys/devices/platform/smapi/BAT0/remaining_percent_error    # error range of remaing_percent (not reset by calibration)
  85 /sys/devices/platform/smapi/BAT0/remaining_running_time     # in minutes, by last minute average power
  86 /sys/devices/platform/smapi/BAT0/remaining_running_time_now # in minutes, by instantenous power
  87 /sys/devices/platform/smapi/BAT0/remaining_charging_time    # in minutes
  88 /sys/devices/platform/smapi/BAT0/remaining_capacity         # in mWh
  89 /sys/devices/platform/smapi/BAT0/design_capacity            # in mWh
  90 /sys/devices/platform/smapi/BAT0/voltage           # in mV
  91 /sys/devices/platform/smapi/BAT0/design_voltage    # in mV
  92 /sys/devices/platform/smapi/BAT0/charging_max_current  # max charging current
  93 /sys/devices/platform/smapi/BAT0/charging_max_voltage  # max charging voltage
  94 /sys/devices/platform/smapi/BAT0/group{0,1,2,3}_voltage # see below
  95 /sys/devices/platform/smapi/BAT0/manufacturer      # string
  96 /sys/devices/platform/smapi/BAT0/model             # string
  97 /sys/devices/platform/smapi/BAT0/barcoding         # string
  98 /sys/devices/platform/smapi/BAT0/chemistry         # string
  99 /sys/devices/platform/smapi/BAT0/serial            # integer
 100 /sys/devices/platform/smapi/BAT0/manufacture_date  # YYYY-MM-DD
 101 /sys/devices/platform/smapi/BAT0/first_use_date    # YYYY-MM-DD
 102 /sys/devices/platform/smapi/BAT0/temperature  # in milli-Celsius
 103 /sys/devices/platform/smapi/BAT0/dump         # see below
 104 /sys/devices/platform/smapi/ac_connected      # 0 or 1
 105
 106 The BAT0/group{0,1,2,3}_voltage attribute refers to the separate cell groups
 107 in each battery. For example, on the ThinkPad 600, X3x, T4x and R5x models,
 108 the battery contains 3 cell groups in series, where each group consisting of 2
 109 or 3 cells  connected in parallel. The voltage of each group is given by these
 110 attributes, and their sum (roughly) equals the "voltage" attribute.
 111 (The effective performance of the battery is determined by the weakest group,
 112 i.e., the one those voltage changes most rapidly during dis/charging.)
 113
 114 The "BAT0/dump" attribute gives a a hex dump of the raw status data, which
 115 contains additional data now in the above (if you can figure it out). Some
 116 unused values are autodetected and replaced by "--":
 117
 118 In all of the above, replace BAT0 with BAT1 to address the 2nd battery (e.g.
 119 in the UltraBay).
 120
 121
 122 Raw SMAPI calls:
 123
 124 /sys/devices/platform/smapi/smapi_request
 125 This performs raw SMAPI calls. It uses a bad interface that cannot handle
 126 multiple simultaneous access. Don't touch it, it's for development only.
 127 If you did touch it, you would so something like
 128 # echo '211a 100 0 0' > /sys/devices/platform/smapi/smapi_request
 129 # cat /sys/devices/platform/smapi/smapi_request
 130 and notice that in the output "211a 34b b2 0 0 0 'OK'", the "4b" in the 2nd
 131 value, converted to decimal is 75: the current charge stop threshold.
 132
 133
 134 Model-specific status
 135 ---------------------
 136
 137 Works (at least partially) on the following ThinkPad model:
 138 * A30
 139 * G41
 140 * R40, R50p, R51, R52
 141 * T23, T40, T40p, T41, T41p, T42, T42p, T43, T43p, T60
 142 * X24, X31, X32, X40, X41, X60
 143 * Z60t, Z61m
 144
 145 Not all functions are available on all models; for detailed status, see:
 146   http://thinkwiki.org/wiki/tp_smapi
 147
 148 Please report success/failure by e-mail or on the Wiki.
 149 If you get a "not implemented" or "not supported" message, your laptop
 150 probably just can't do that (at least not via the SMAPI BIOS).
 151 For negative reports, follow the bug reporting guidelines below.
 152 If you send me the necessary technical data (i.e., SMAPI function
 153 interfaces), I will support additional models.
 154
 155
 156 Additional HDAPS features
 157 -------------------------
 158
 159 The modified hdaps driver has several improvements on the one in mainline
 160 (beyond resolving the conflict with thinkpad_ec and tp_smapi):
 161
 162 - Fixes reliability and improves support for recent ThinkPad models
 163   (especially *60 and newer). Unlike the mainline driver, the modified hdaps
 164   correctly follows the Embedded Controller communication protocol.
 165
 166 - Extends the "invert" parameter to cover all possible axis orientations.
 167   The possible values are as follows.
 168   Let X,Y denote the hardware readouts.
 169   Let R denote the laptop's roll (tilt left/right).
 170   Let P denote the laptop's pitch (tilt forward/backward).
 171     invert=0:   R= X  P= Y   (same as mainline)
 172     invert=1:   R=-X  P=-Y   (same as mainline)
 173     invert=2:   R=-X  P= Y   (new)
 174     invert=3:   R= X  P=-Y   (new)
 175     invert=4:   R= Y  P= X   (new)
 176     invert=5:   R=-Y  P=-X   (new)
 177     invert=6:   R=-Y  P= X   (new)
 178     invert=7:   R= Y  P=-X   (new)
 179   It's probably easiest to just try all 8 possibilities and see which yields
 180   correct results (e.g., in the hdaps-gl visualisation).
 181
 182 - Adds a whitelist which automatically sets the correct axis orientation for
 183   some models. If the value for your model is wrong or missing, you can override
 184   it using the "invert" parameter. Please also update the tables at
 185   http://www.thinkwiki.org/wiki/tp_smapi and
 186   http://www.thinkwiki.org/wiki/List_of_DMI_IDs
 187   and submit a patch for the whitelist in hdaps.c.
 188
 189 - Provides new attributes:
 190   /sys/devices/platform/hdaps/sampling_rate:
 191     This determines the frequency at which the host queries the embedded
 192     controller for accelerometer data (and informs the hdaps input devices).
 193     Default=50.
 194   /sys/devices/platform/hdaps/oversampling_ratio:
 195     When set to X, the embedded controller is told to do physical accelerometer
 196     measurements at a rate that is X times higher than the rate at which
 197     the driver reads those measurements (i.e., X*sampling_rate). This
 198     makes the readouts from the embedded controller more fresh, and is also
 199     useful for the running average filter (see next). Default=5
 200   /sys/devices/platform/hdaps/running_avg_filter_order:
 201     When set to X, reported readouts will be the average of the last X physical
 202     accelerometer measurements. Current firmware allows 1<=X<=8. Setting to a
 203     high value decreases readout fluctuations. The averaging is handled by the
 204     embedded controller, so no CPU resources are used. Higher values make the
 205     readouts smoother, since it averages out both sensor noise (good) and abrupt
 206     changes (bad). Default=2.
 207
 208 - Provides a second input device, which publishes the raw accelerometer
 209   measurements (without the fuzzing needed for joystick emulation). This input
 210   device can be matched by a udev rule such as the following (all on one line):
 211     KERNEL=="event[0-9]*", ATTRS{phys}=="hdaps/input1",
 212     ATTRS{modalias}=="input:b0019v1014p5054e4801-*",
 213     SYMLINK+="input/hdaps/accelerometer-event
 214
 215 A new version of the hdapsd userspace daemon, which uses the input device
 216 interface instead of polling sysfs, is available seprately. Using this reduces
 217 the total interrupts per second generated by hdaps+hdapsd (on tickless kernels)
 218 to 50, down from a value that fluctuates between 50 and 100. Set the
 219 sampling_rate sysfs attribute to a lower value to further reduce interrupts,
 220 at the expense of response latency.
 221
 222 Licensing note: all my changes to the HDAPS driver are licensed under the
 223 GPL version 2 or, at your option and to the extent allowed by derivation from
 224 prior works, any later version. My version of hdaps is derived work from the
 225 mainline version, which at the time of writing is available only under
 226 GPL version 2.
 227
 228 Bug reporting
 229 -------------
 230
 231 Mail <multinymous@gmail.com>. Please include:
 232 * Details about your model,
 233 * Relevant "dmesg" output. Make sure thinkpad_ec and tp_smapi are loaded with
 234   the "debug=1" parameter (e.g., use "make load HDAPS=1 DEBUG=1").
 235 * Output of "dmidecode | grep -C5 Product"
 236 * Does the failed functionality works under Windows?
 237
 238
 239 More about SMAPI
 240 ----------------
 241
 242 For hints about what may be possible via the SMAPI BIOS and how, see:
 243
 244 * IBM Technical Reference Manual for the ThinkPad 770
 245   (http://www-307.ibm.com/pc/support/site.wss/document.do?lndocid=PFAN-3TUQQD)
 246 * Exported symbols in PWRMGRIF.DLL or TPPWRW32.DLL (e.g., use "objdump -x").
 247 * drivers/char/mwave/smapi.c in the Linux kernel tree.*
 248 * The "thinkpad" SMAPI module (http://tpctl.sourceforge.net).
 249 * The SMAPI_* constants in tp_smapi.c.
 250
 251 Note that in the above Technical Reference and in the "thinkpad" module,
 252 SMAPI is invoked through a function call to some physical address. However,
 253 the interface used by tp_smapi and the above mwave drive, and apparently
 254 required by newer ThinkPad, is different: you set the parameters up in the
 255 CPU's registers and write to ports 0xB2 (the APM control port) and 0x4F; this
 256 triggers an SMI (System Management Interrupt), causing the CPU to enter
 257 SMM (System Management Mode) and run the BIOS firmware; the results are
 258 returned in the CPU's registers. It is not clear what is the relation between
 259 the two variants of SMAPI, though the assignment of error codes seems to be
 260 similar.
 261
 262 In addition, the embedded controller on ThinkPad laptops has a non-standard
 263 interface at IO ports 0x1600-0x161F (mapped to LCP channel 3 of the H8S chip).
 264 The interface provides various system management services (currently known:
 265 battery information and accelerometer readouts). For more information see the
 266 thinkpad_ec module and the H8S hardware documentation:
 267 http://documentation.renesas.com/eng/products/mpumcu/rej09b0300_2140bhm.pdf