Toshiba Acpi

In addition to the standard interface required of ACPI implementations, hardware vendors may also include a custom interface to control hardware configuration. In the past, such control was done through BIOS calls, special CPU modes, or a boot-time configuration utility. However, the latest laptops by Toshiba are different in that use of ACPI methods is the only way to control certain devices. (Is this really true? In the end doesn't even ACPI code have to access the hardware using memory access, I/O port access, or software interrupt?)

Ideally we would like Toshiba to provide a programming specification for their ACPI methods. An application to Toshiba for the necessary info has been made [1]. Until that happens, we must rely on reverse engineering.

Known Methods

INPUT: 6 integers (HCI registers)

OUTPUT: 6 integers (HCI registers)

HCI is Toshiba's hardware control interface. This interface is uniform across most of their laptops, including models without ACPI. See Jonathan Buzzard's site [2] for details about HCI.

\_SB_.PCI0.VGA_.LCD_._BCM - Set the LCD brightness.

INPUT: integer brightness value (0-7)

OUTPUT: none

This is implemented by just making a call to the HCI. There is no corresponding method to read the brightness, so in that case the HCI must be called directly.

\_SB_.VALX.DSSX - Set video output channels.

INPUT: integer code (bit 0 is LCD, bit 1 is CRT, bit 2 is TV)

OUTPUT: none

This method not only sets the video output of the graphic chip, but also turns the LCD and backlight on or off as needed.

Viewing ACPI Dissasembly

To peek at the ACPI contents you will need to install a package called pmtools, available from the Intel ACPI site [3]. (Note that this package is different from the "Perl module tools" package of the same name.) It is also necessary to enable ACPI in your kernel configuration.

To dump the disassembly, use this command:

acpidmp DSDT | acpidisasm

Here is a hint about Toshiba's ACPI code. Wherever a list of four numbers starting with 0xff00 or 0xfe00 appears, the code is doing an HCI call. For example:

00001278:               <NULL>
0000127c:               0xff00
0000127f:               0x23
00001281:               0x80
00001283:               0x00

The call above is a write to HCI register 0x23 with values 0x80 and 0x00. Since many of the HCI codes are known from previous Toshiba driver work, these act as indicators to the purpose of an ACPI method.

NOTE: it appears that the dissasembler is not complete. When it encounters something unknown, <NULL> is displayed. In the case above, it is probably a subroutine call.

More Disassembly Practice

If you feed this through iasl from the same site [3] instead, you get things like: (This is the GHCI code \_SB_.VALD.GHCI mentioned above.)

For reference, this langauge is documented in section 16 of the ACPI 2.0b spec (page 353 onwards). The names starting with _ are documented on page 164 onwards.

Method (GHCI, 6, Serialized) {
        Store (Arg4, \_SB.MEM.IESI)
        Store (Arg5, \_SB.MEM.IEDI)
        SMBR (Arg0, Arg1, Arg2, Arg3, 0xB2)
        Name (BUFF, Package (0x06) {})
        Store (\_SB.MEM.OEAX, Index (BUFF, 0x00))
        Store (\_SB.MEM.OEBX, Index (BUFF, 0x01))
        Store (\_SB.MEM.OECX, Index (BUFF, 0x02))
        Store (\_SB.MEM.OEDX, Index (BUFF, 0x03))
        Store (\_SB.MEM.OESI, Index (BUFF, 0x04))
        Store (\_SB.MEM.OEDI, Index (BUFF, 0x05))
        Return (BUFF)
} 

Where the code listed above (00001278 to 00001283) is the SMBR (Arg0, Arg1, Arg2, Arg3, 0xB2) line.

The SMBR function is as follows: (This and the above is from a Toshbia Satellite Pro 4600's 2.50 ACPI Bios, as uploaded to the DSDT repository on the acpi project sourceforge site [4]. So you can try this at home. :-)

Method (SMBR, 5, NotSerialized) {
        Store (Arg0, \_SB.MEM.IEAX)
        Store (Arg1, \_SB.MEM.IEBX)
        Store (Arg2, \_SB.MEM.IECX)
        Store (Arg3, \_SB.MEM.IEDX)
        Store (Arg4, \_SB.PCI0.FNC0.SYSR.TRP4)
}

Which is a HCI/SCI call, just as you'd expect. So you can see all the HCI calls being made in the iasl output for your laptop with grep SMBR dsdt.dsl assuming dsdt.dsl is the disassembled output from your DSDT table in /proc/acpi/dsdt. (That last line is presumably the new way of accessing HCI. Its definition is below)

OperationRegion (SRG1, SystemIO, 0xB2, 0x01)

Field (SRG1, ByteAcc, NoLock, Preserve) {
        TRP4,   8
}

This says that a region called SRG1 at SystemIO address 0xB2 (one byte long) is put aside for the exclusive use of ACPI. This means an ACPI-enabled machine _shouldn't_ have it's HCI accessed via any other method than ACPI.... And within that region, 8 bits are marked as field TRP4. Why they write 0xB2 to 0xB2 I don't know... However, in other places other values are written to B2, such as docking (0x05 and 0x40) and undocking (0x40), and during initialisation of PCI0 (0x60). It's interesting to note that IO address 0xB2 is _written to_ here, rather than read from under plain HCI, and the value written appears to be relevant. Certainly there's no evidence of SCI calls.

With this information in hand, we can see in my DSDT file that \_SB_.VALX.DSSX doesn't exist, but the \_SB.PCI0.PCI1.VGA.{LCD,CRT,TV}._DSS functions work as expected, via SMBR with Arg1==0x1c, and in theory the video state could be queried via ._DCS or ._DGS and they also are just abstractions to SMBR (and hence to HCI) as well. The LCD object supplies the standard brightness control functions _BCL and _BCM, so the ACPI functionality supplied is pretty good.

Another interesting block of code is the fan powerresource block, as follows:

PowerResource (PFAN, 0x00, 0x0000) {
        Method (_STA, 0, NotSerialized)
        {
                SMBR (0xFA00, 0x2201, 0x00, 0x00, 0xB2)
                If (\_SB.MEM.OECX) {
                        Return (One)
                }
                Else
                {
                        Return (0x00)
                }
        }

        Method (_ON, 0, Serialized) {
                SMBR (0xFA00, 0x2200, 0xFF, 0x00, 0xB2)
        }

        Method (_OFF, 0, Serialized) {
                SMBR (0xFA00, 0x2200, 0x00, 0x00, 0xB2)
        }
}

Which also writes to 0xB2 with 0xB2, and AX=0xFA00, BX=0x2201 for query and BX=0x2200 for set speed with CX=0xFF for on and CX=0x00 for off. IE Not HCI as we know it! Of course, this is only of minor interest since the point of HCI is to have a single interface for all Toshiba laptops, regardless of type. And without testing, we don't know if this method of fan control is new or simply previously unnoticed. (I expect it's new...)

Anyway, the upshot here is that (a) the standard ACPI tools should be able to read/control the standard device settings (_XXX methods). I've no idea why video output brightness/output device control don't show up in /proc/acpi. Maybe no-one's bothered? Nor why the standard ACPI tools don't seem to be able to read my fan's current status; (b) a survey of the DSDTs from Toshiba laptops needs to be done to determine what other custom methods are supplied... It looks to me like all custom methods are supplied in \_SB.VALD, and (at least for my bios) that's only ENAB, INFO and GHCI, with ENAB and INFO being uninteresting. Certainly Toshiba distributes a driver for Win98SE and Win2K/XP which supports device TOS6200, which is the VALD on my machine. (A quick google search suggests the Libretto 100 also has a TOS6200 VALD)

We can also survey the bioses to identify unknown HCI commands, and the structure of the DSDT will give good hints as to what they are and what they do. I certainly hit a lot of HCI commands that don't show up in the documents from Johnathan Buzzard's website.

That's interesting stuff. One problem is that these method paths are dependent on where devices are connected on the PCI bus. (Clearly the paths for the Satellite 4600 and Libretto L's are different.) Is there some way to determine these paths automatically?