The [[wikipedia:Super I/O|Super I/O]] is a chip found on most of today's mainboards which is &mdash; among other things &mdash; responsible for the serial ports of the mainboard (e.g. COM1, COM2). This chip is usually the first thing you'll want to support, as it's required to get serial debugging output from the mainboard (via a null-modem cable and the proper software, e.g. [[minicom]] or CuteCom).

+

The [[wikipedia:Super I/O|Super I/O]] is a chip found on most of today's mainboards which is &mdash; among other things &mdash; responsible for the serial ports of the mainboard (e.g. COM1, COM2).

+

This chip is usually the first thing you'll want to support, as it's required to get serial debugging output from the mainboard (via a null-modem cable and the proper software, e.g. minicom or CuteCom).

* In that directory, add a file ''device''_early_serial.c (e.g. w83627ehg_early_serial.c). This file will be responsible to setup a serial port on the mainboard so that you can get serial debugging output. This will work even ''before'' the RAM is initialized, thus is useful/required for debugging the RAM initialization process.

+

Adding support for a new Super I/O chip is usually not significantly hard once you have obtained the datasheet for your target chip. Herein we shall outline the steps usally taken for a bringup.

−

* In this file you now declare a function ''device''_enable_serial() which enables the requested serial port. Example:

You can find out what LDN's your chip has from its data-sheet LDN summary table.

+

+

== early_serial.c ==

+

+

The '''src/superio/''vendor''/''device'''''/''early_serial.c'' file will be responsible to setup a serial port on the mainboard as to get serial debugging output.

+

N.B. This will work even ''before'' the RAM is initialized, thus is useful/required for debugging the RAM initialization process.

+

In this file you now declare a function '''''device''_enable_serial()''' which enables the requested serial port.

+

For example:

+

void w83627ehg_enable_serial(device_t dev, unsigned int iobase)

{

{

pnp_enter_ext_func_mode(dev);

pnp_enter_ext_func_mode(dev);

Line 17:

Line 75:

pnp_exit_ext_func_mode(dev);

pnp_exit_ext_func_mode(dev);

}

}

−

* Mainboards which have this Super I/O chip, will call this function in their ''auto.c'' or ''cache_as_ram_auto.c'' file. Example:

+

where we defined the functions prototype in the '''src/superio/''vendor''/''device'''''/''device.h'' as to link it into both the rom and ram stages.

−

#include "superio/winbond/w83627ehg/w83627ehg_early_serial.c"

+

We also must statically declarate two helper functions:

+

/*

+

* Enable configuration: pass entry key '0x87' into index port dev.

+

*/

+

static void pnp_enter_conf_state(device_t dev)

+

{

+

» u16 port = dev >> 8;

+

» outb(0x87, port);

+

» outb(0x87, port);

+

}

+

+

/*

+

* Disable configuration: pass exit key '0xAA' into index port dev.

+

*/

+

static void pnp_exit_conf_state(device_t dev)

+

{

+

» u16 port = dev >> 8;

+

» outb(0xaa, port);

+

}

+

+

These two procedures are what put the Super I/O chip into ''configuration mode'' and then return it back again..

+

N.B. The values of 0x87 and 0xAA for enable and disable configuration respectively are typical although check the Super I/O data sheet to be sure.

+

N.B. The default index port and data port are either '''0x4E''' and '''0x4F''' or '''0x2E''' and '''0x2F''' respecively, once again check the data sheet.

+

:Whether the Super I/O is at config address '''0x2e''' (the usual case) or '''0x4e''' (or some other address) is mainboard-dependent. You can find out the address by running [[superiotool]].

+

This value is usually defined in the mainboards ''devicetree.cb'' file under the pnp device in any case.

+

+

Mainboards which have this Super I/O chip, will call this function in their '''romstage.c''' file. Example:

+

#include "superio/winbond/w83627ehg/w83627ehg.h"

[...]

[...]

#define SERIAL_DEV PNP_DEV(0x2e, W83627EHG_SP1)

#define SERIAL_DEV PNP_DEV(0x2e, W83627EHG_SP1)

[...]

[...]

w83627ehg_enable_dev(SERIAL_DEV, TTYS0_BASE);

w83627ehg_enable_dev(SERIAL_DEV, TTYS0_BASE);

−

uart_init();

console_init();

console_init();

−

:Whether the Super I/O is at config address ''0x2e'' (the usual case) or ''0x4e'' (or some other address) is mainboard-dependent. You can find out the address by running [[superiotool]].

−

=== Virtual logical devices ===

+

== superio.c ==

−

Some Super I/Os use register 0x30 of one logical device number (LDN) for more then one function enable. For example, it can be used to enable some GPIOs, GAME, MIDI etc. To overcome this issue a concept of virtual LDN has been introduced. Virtual LDNs can be used in coreboot to map the enable bit position in register 0x30 to virtual LDN, which will just enable the functionality map to that bit.

+

While writing the superio.c part of the Super I/O bring up you will encounter the data structure static struct pnp_info pnp_dev_info[] = {} to prepare.

+

The following information may help to understand the LDN mask pairing:

−

Original LDN always just switch on or off bit0 of register 0x30. Virtual LDN is created as follows.

+

/*

−

Low [7:0] bits are used to describe the original LDN. High [10:8] bits select the position of the bit enable in the register 0x30.

+

* io_info contains the mask 0x07f8. Given 8 register, each 8 bits wide of a

+

* logical device we need a mask of the following form:

+

*

+

* MSB LSB

+

* v v

+

* 0x[15..11][10..3][2..0]

+

* ------ ^^^^^ ^^^^

+

* null | |

+

* | +------ Register index

+

* |

+

* +------------- Compare against base address and

+

* asserts a chip_select on match.

+

*

+

* i.e., 0x07F8 = [00000][11111111][000]

+

*

+

*/

−

If LDN is 0x7 it will handle bit0 of register 0x30. If the (virtual) LDN is 0x107 it will handle bit1 of same register etc.

Latest revision as of 00:15, 24 February 2014

The Super I/O is a chip found on most of today's mainboards which is — among other things — responsible for the serial ports of the mainboard (e.g. COM1, COM2).
This chip is usually the first thing you'll want to support, as it's required to get serial debugging output from the mainboard (via a null-modem cable and the proper software, e.g. minicom or CuteCom).

Contents

Super I/O bringup

Adding support for a new Super I/O chip is usually not significantly hard once you have obtained the datasheet for your target chip. Herein we shall outline the steps usally taken for a bringup.

Virtual Logical Devices (LDN)

Many Super I/O's use register 0x30 of one logical device number (LDN) for more than one function enable.
For example, it can be used to enable some GPIOs, GAME, MIDI etc. To overcome this issue a concept of virtual LDN has been introduced.

Virtual LDN's can be used in Coreboot to map the enable bit position in register 0x30 to virtual LDN, which will just enable the functionality map to that bit.

Original LDN always just switch on or off bit0 of register 0x30, however a virtual LDN is created as follows.
Low [7:0] bits are used to describe the original LDN. High [10:8] bits select the position of the bit enable in the register 0x30.
If LDN is 0x7 it will handle bit0 of register 0x30. If the (virtual) LDN is 0x107 it will handle bit1 of same register etc.

TODO: Improvements needed here for the layman.

Source layout

Create the top-level directory src/superio/vendor/device (e.g. src/superio/winbond/w83627ehg).
Within src/superio/vendor edit both Kconfig and Makefile.inc the changes will be self-evident.
All super i/o support is then contained in src/superio/vendor/device, we provide here the minimum of a usual bringup.

Makefile.inc

The src/superio/vendor/device/Makefile.inc should contain the following two lines:

You can find out what LDN's your chip has from its data-sheet LDN summary table.

early_serial.c

The src/superio/vendor/device/early_serial.c file will be responsible to setup a serial port on the mainboard as to get serial debugging output.
N.B. This will work even before the RAM is initialized, thus is useful/required for debugging the RAM initialization process.
In this file you now declare a function device_enable_serial() which enables the requested serial port.
For example:

These two procedures are what put the Super I/O chip into configuration mode and then return it back again..
N.B. The values of 0x87 and 0xAA for enable and disable configuration respectively are typical although check the Super I/O data sheet to be sure.
N.B. The default index port and data port are either 0x4E and 0x4F or 0x2E and 0x2F respecively, once again check the data sheet.

Whether the Super I/O is at config address 0x2e (the usual case) or 0x4e (or some other address) is mainboard-dependent. You can find out the address by running superiotool.

This value is usually defined in the mainboards devicetree.cb file under the pnp device in any case.

Mainboards which have this Super I/O chip, will call this function in their romstage.c file. Example:

superio.c

While writing the superio.c part of the Super I/O bring up you will encounter the data structure static struct pnp_info pnp_dev_info[] = {} to prepare.
The following information may help to understand the LDN mask pairing: