The wiki is being retired!

Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!

About

The current status of the OpenVSA is: experimental. Please do not use OpenVSA in your system unless you have access to a low-level re-flashing tools.

To obtain the OpenVSA sources, refer to download coreboot.

Context

VSA, or Virtual System Architecture is a low-level software library included in the bootloader/BIOS for system using AMD Geode-series CPUs and companion chips.

AMD released VSA sources under the GNU LGPL in 2006. Those sources were hosted by the OLPC project, and can be pulled with git from git://dev.laptop.org/geode-vsa. The OpenVSA sources include modified Geode VSA sources, as well as some new components also released under the GNU LGPL.

The VSA code runs under x86 SMM (System Management Mode) which is like "real mode" with some extra opcodes, priviledges, and side-effects.

As originally published, the VSA code compiled and assembled with older, commercially unavailable versions of Microsoft tools. The OpenVSA code has been modified in order to build under a GNU toolchain so that it may be maintained and enhanced by a wider group of users.

Differences Between VSA and OpenVSA

Summary

Category	VSA	OpenVSA
Assembler	MASM 6.11c or greater	GNU gas (part of binutils)
Make	NMAKE.EXE Version 1.40 or greater	GNU make
C-compiler	MSVC Version 1.52	GNU gcc
Final binary output	exe2bin.exe	GNU objcopy (part of binutils)
Assembly syntax	Microsoft/Intel	GNU gas/AT&T
Code Generation	16-bit, inherent to the toolchain commands used during build	16-bit assembly, generated by using `.code16` in assembly files; 32-bit from C, prefixes generated by using `.code16gcc` in C files
Memory Model	"tiny": merges CS and DS, inherent to the toolchain commands used during build	"tiny" model accomplished with specific section names and linker script statements
SMM-only opcode assembly	MASM macros	Perl script `smimac.pl` pre-processes to constant-sequences
Internal assembly functions: calling convention	custom/random, no apparent fixed pattern	unchanged
Assembly functions called from C: calling convention	Microsoft `pascal`	GNU `__attribute__((fastcall))`
C header file translation to assembly include	h2inc.exe	manual/static translation

Calling Conventions And Stack

VSA: MASM and Microsoft C

The original VSA sources used 16-bit MS PASCAL calling convention (__pascal):

stack parameter order: left-to-right
called function cleans up the stack
all parameters are pushed onto the stack
return values to 16 bits returned in AX
return values 17 to 32 bits returned in DX:AX
scratch registers AX, BX, CX, DX, ES

^           |<- 16 bits ->|
| higher
| address
| (pop)

             -------------
            | first param |
             -------------
                  ...
             -------------
            |  last param |   4(BP)
             -------------
            |  return IP  |   2(BP)
             -------------
            |   old BP    | <-- BP
             -------------
                (locals)     -2(BP)
             -------------
              (saved regs)
             -------------
            | (saved reg) | <-- SP
             -------------

| lower
| address
| (push)
v

OpenVSA: GNU

With GNU on the Intel 386, the fastcall attribute (__attribute__(fastcall)) calling convention:

stack parameter order: right-to-left
called function cleans up the stack
if the first one or two arguments are integers/pointers (<=32bit), they are passed via ECX and EDX
all other parameters are pushed onto the stack
return values to 32 bits are returned in EAX
scratch registers EAX, ECX, EDX

^           |<- 32 bits ->|
| higher
| address
| (pop)                      (uses              (no
                              frame)             frame)

             -------------
            | last param  |
             -------------
                  ...
             -------------
            |  3rd param  |   8(EBP)            4(ESP)
             -------------
            | return EIP  |                   <-- ESP
             -------------
            |  saved EBP  | <-- EBP
             -------------
                (locals)     -4(EBP)
             -------------
              (saved regs)
             -------------
              (saved reg)   <-- ESP
| lower
| address
| (push)
v

Notable C-Code Differences

Microsoft C appears to accept a statement like:

 ULONG Data;
 ...
 (UCHAR)Data = 0;

This is not a portable construction, GCC rejects is, so has been changed to:

 *((UCHAR *) &Data) = 0;

Feature Wish List

TODO.

Hacking Notes

TODO.

Licenses

OpenVSA Software

This work is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or any later version. This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

This Article

I, the copyright holder of this work, hereby release it into the public domain. This applies worldwide.

In case this is not legally possible:
I grant anyone the right to use this work for any purpose, without any conditions, unless such conditions are required by law.

OpenVSA