Difference between revisions of "Developer Manual/Super IO"
AvengerF12 (talk | contribs) m (→Logical Devices (LDN)) |
AvengerF12 (talk | contribs) (Fleshed out a bit more the subject and clarified some things) |
||
| Line 34: | Line 34: | ||
== Virtual Logical Devices (vLDN) == | == Virtual Logical Devices (vLDN) == | ||
| − | + | Some Super I/O's use register 0x30 of one of the logical device numbers (LDN) to also enable other logical device's functions. | |
| − | For example, | + | For example, in the case of the W83627EHF chip, register 0x30 of LDN 0x9 was used to enable multiple devices (GPIO2 = bit0, GPIO3 = bit1, GPIO4 = bit2 and GPIO5 = bit3). To overcome this issue a concept of virtual LDN has been [https://www.coreboot.org/pipermail/coreboot/2008-February/030912.html introduced]. |
| − | Virtual LDN's can be used in Coreboot to map the enable bit position in register 0x30 | + | Virtual LDN's can be used in Coreboot to uniquely map the enable bit position in register 0x30 of an LDN, this allows to use a general way to handle any bit enable operation required without special cases. |
| − | + | Originally, except in cases such as the W83627EHF's, to enable or disable an LDN's functionality you only had to just switch on or off bit0 of the 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 | + | * 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. | |
| − | + | Note: the bit positions are in hex. | |
| + | |||
| + | I.e. W83627EHF chip | ||
| + | |||
| + | In order to enable the GPIO5 (bit3 of register 0x30) this is what the virtual LDN has to look like this: | ||
| + | |||
| + | *[0000 0011] [0000 1001] = 0x309 | ||
| + | * ^^^^^^^^^ ^^^^^^^^^ | ||
| + | * | | | ||
| + | * | +------- Original LDN | ||
| + | * | | ||
| + | * | | ||
| + | * +------- Position inside register 0x30 | ||
| + | |||
| + | Note: if the virtual LDN is 0x7 it will handle bit0 of register 0x30. | ||
== Source layout == | == Source layout == | ||
Revision as of 23:22, 2 March 2016
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.
Logical Devices (LDN)
Every Super I/O chip provides different kinds of functions to the computer, such as control over GPIOs, GAME port, MIDI port, fan controllers, infrared and more.
Each of these functions, inside a Super I/O, is split into its own logical device and everyone of these devices is identified by an hex number (starting from 0x0) called logical device number (LDN). I.e. (addr) 0x05 and 0x06 are the LDN respectively for the keyboard and the mouse.
Check your chip's datasheet to find the complete list.
Super I/O configuration
A Super I/O chip can be configured through the use of its configuration registers.
These registers can be divided into two classes:
- Super I/O control and configuration
- Logical Device control and configuration
The first class contains all the registers that have the same value no matter which LDN has been selected, a sort of "global" register. An example of this class can be found in the LDN register (addr 0x7) which is used to select an LDN, the Super I/O ID register (addr 0x20) and the Revision ID register (addr 0x27) which contain respectively the ID and the revision number of your chip.
The second class includes all the registers that are relative to the LDN that has been previously selected. Among these ones there is the Logical Device Control register (addr 0x30) which is used to enable or disable the functionality of that Logical Device, the I/O Address register (addr 0x60-0x61) which are used to access runtime registers, and others.
Virtual Logical Devices (vLDN)
Some Super I/O's use register 0x30 of one of the logical device numbers (LDN) to also enable other logical device's functions. For example, in the case of the W83627EHF chip, register 0x30 of LDN 0x9 was used to enable multiple devices (GPIO2 = bit0, GPIO3 = bit1, GPIO4 = bit2 and GPIO5 = bit3). To overcome this issue a concept of virtual LDN has been introduced.
Virtual LDN's can be used in Coreboot to uniquely map the enable bit position in register 0x30 of an LDN, this allows to use a general way to handle any bit enable operation required without special cases.
Originally, except in cases such as the W83627EHF's, to enable or disable an LDN's functionality you only had to just switch on or off bit0 of the 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.
Note: the bit positions are in hex.
I.e. W83627EHF chip
In order to enable the GPIO5 (bit3 of register 0x30) this is what the virtual LDN has to look like this:
- [0000 0011] [0000 1001] = 0x309
- ^^^^^^^^^ ^^^^^^^^^
- | |
- | +------- Original LDN
- |
- |
- +------- Position inside register 0x30
Note: if the virtual LDN is 0x7 it will handle bit0 of register 0x30.
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:
romstage-$(CONFIG_SUPERIO_VENDOR_DEVICE) += early_serial.c ramstage-$(CONFIG_SUPERIO_VENDOR_DEVICE) += superio.c
Obviously replacing VENDOR and DEVICE respectively.
device.h, (e.g., w83627ehg.h)
The src/superio/vendor/device/device.h header should contain the Super I/O supported Logical Device Numbers (LDN) and the early_serial enabling function prototype.
For example, for f71869ad.h we have:
#ifndef SUPERIO_FINTEK_F71869AD_F71869AD_H #define SUPERIO_FINTEK_F71869AD_F71869AD_H /* Logical Device Numbers (LDN). */ #define F71869AD_FDC 0x00 /* Floppy */ #define F71869AD_SP1 0x01 /* UART1 */ #define F71869AD_SP2 0x02 /* UART2 */ #define F71869AD_PP 0x03 /* Parallel port */ #define F71869AD_HWM 0x04 /* Hardware monitor */ #define F71869AD_KBC 0x05 /* PS/2 keyboard and mouse */ #define F71869AD_GPIO 0x06 /* General Purpose I/O (GPIO) */ #define F71869AD_BSEL 0x07 /* BSEL */ #define F71869AD_PME 0x0a /* Power Management Events (PME) and ACPI */ void f71869ad_enable_serial(device_t dev, u16 iobase); #endif /* SUPERIO_FINTEK_F71869AD_F71869AD_H */
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_set_logical_device(dev);
pnp_set_enable(dev, 0);
pnp_set_iobase(dev, PNP_IDX_IO0, iobase);
pnp_set_enable(dev, 1);
pnp_exit_ext_func_mode(dev);
}
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. 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)
{
}
/*
* Disable configuration: pass exit key '0xAA' into index port dev.
*/
static void pnp_exit_conf_state(device_t dev)
{
}
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) [...] w83627ehg_enable_dev(SERIAL_DEV, TTYS0_BASE); console_init();
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:
/* * 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] * */
A typical superio.c would look like this:
#include <arch/io.h>
#include <device/device.h>
#include <device/pnp.h>
#include <superio/conf_mode.h>
#include <console/console.h>
#include <stdlib.h>
#include "f71869ad.h"
static void f71869ad_init(device_t dev)
{
{
}
static struct device_operations ops = {
};
static struct pnp_info pnp_dev_info[] = {
{ &ops, F71869AD_FDC, PNP_IO0 | PNP_IRQ0 | PNP_DRQ0, {0x07f8, 0}, }, { &ops, F71869AD_SP1, PNP_IO0 | PNP_IRQ0, {0x07f8, 0}, }, { &ops, F71869AD_SP2, PNP_IO0 | PNP_IRQ0, {0x07f8, 0}, }, { &ops, F71869AD_PP, PNP_IO0 | PNP_IRQ0 | PNP_DRQ0, {0x07f8, 0}, }, { &ops, F71869AD_HWM, PNP_IO0 | PNP_IRQ0, {0x0ff8, 0}, }, { &ops, F71869AD_KBC, PNP_IO0 | PNP_IRQ0 | PNP_IRQ1, {0x07ff, 0}, }, { &ops, F71869AD_GPIO, }, { &ops, F71869AD_BSEL, PNP_IO0, {0x07f8, 0}, }, { &ops, F71869AD_PME, },
};
static void enable_dev(device_t dev)
{
}
struct chip_operations superio_fintek_f71869ad_ops = {
};
Additional resources
If you still have some problems these could come in handy:
