Difference between revisions of "Developer Manual/Super IO"

From coreboot
Jump to navigation Jump to search
(Attempt 1 at writing a Super I/O bring up guide.. (WIP).)
Line 1: Line 1:
The [[wikipedia:Super I/O|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).
The [[wikipedia:Super I/O|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).


[[Image:Winbond w83977ef.jpg|thumb|right|<small>Winbond W83977EF Super&nbsp;I/O</small>]]
[[Image:Winbond w83977ef.jpg|thumb|right|<small>Winbond W83977EF Super&nbsp;I/O</small>]]
[[Image:Ite it8705f.jpg|thumb|right|<small>ITE IT8705F Super&nbsp;I/O</small>]]
[[Image:Ite it8705f.jpg|thumb|right|<small>ITE IT8705F Super&nbsp;I/O</small>]]


The steps for adding support for a new Super I/O chip are:
= Super I/O bringup =
* Add a directory '''src/superio/''vendor''/''device''''' (e.g. '''src/superio/winbond/w83627ehg''').
 
* 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:
 
   static void w83627ehg_enable_serial(device_t dev, unsigned int iobase)
== 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) (see below) 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). */
 
  void f71869ad_enable_serial(device_t dev, u16 iobase);
 
  #endif /* SUPERIO_FINTEK_F71869AD_F71869AD_H */
 
=== 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 60:
         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 '''romstage.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)
  {
  }
 
  /*
  * 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)
   #define SERIAL_DEV PNP_DEV(0x2e, W83627EHG_SP1)
Line 25: Line 95:
   uart_init();
   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]].


=== superio.c ===
=== superio.c ===

Revision as of 12:46, 5 February 2014