Return to README CVS log

Up to [Qemu by Fabrice Bellard] / qemu / roms / SLOF

Annotation of qemu/roms/SLOF/README, revision 1.1

1.1     ! root        1: Slimline Open Firmware - SLOF
        !             2: 
        !             3: Copyright (C) 2004, 2008  IBM Corporation
        !             4: 
        !             5: 
        !             6: Index
        !             7: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
        !             8: 1.0 Introduction to Open Firmware
        !             9: 1.1 Build process
        !            10: 2.0 Extension
        !            11: 3.0 Limitations
        !            12: 
        !            13: 1.0 Introduction to Open Firmware
        !            14: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
        !            15: 
        !            16: The IEEE Standard 1275-1994 [1], Standard for Boot (Initialization Configuration)
        !            17: Firmware, Core Requirements and Practices, is the first non-proprietary open
        !            18: standard for boot firmware that is usable on different processors and buses.
        !            19: Firmware which complies with this standard (also known as Open Firmware)
        !            20: includes a processor-independent device interface that allows add-in devices
        !            21: to identify itself and to supply a single boot driver that can be used,
        !            22: unchanged, on any CPU.  In addition, Open Firmware includes a user interface
        !            23: with powerful scripting and debugging support and a client interface that
        !            24: allows an operating system and its loaders to use Open Firmware services
        !            25: during the configuration and initialization process.  Open Firmware stores
        !            26: information about the hardware in a tree structure called the
        !            27: ``device tree''.  This device tree supports multiple interconnected system
        !            28: buses and offers a framework for ``plug and play''-type auto configuration
        !            29: across different buses.  It was designed to support a variety of different
        !            30: processor Instruction Set Architectures (ISAs) and buses.
        !            31: 
        !            32: The full documentation of this Standard can be found in [1].
        !            33: 
        !            34: 
        !            35: 1.1 Build process
        !            36: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
        !            37: 
        !            38: Open Firmware (OF) is based on the programming language Forth. 
        !            39: SLOF use Paflof as the Forth engine, which was developed by
        !            40: Segher Boessenkool.  Most parts of the Forth engine are implemented in 
        !            41: C, by using GNU extensions of ANSI C, (e.g. assigned goto, often misnamed "computed goto"),
        !            42: resulting in a very efficient yet still quite portable engine.  
        !            43: 
        !            44: The basic Forth words, so-called primitives,  are implemented with 
        !            45: a set of C macros.  A set of .in and .code files are provided, which
        !            46: define the semantic of the Forth primitives.  A Perl script translates 
        !            47: these files into valid C code, which will be compiled into the Forth engine.
        !            48: The complete Forth system composes of the basic Forth primitives and
        !            49: a set of Forth words, which are compiled during the start of the Forth
        !            50: system.
        !            51: 
        !            52: Example:
        !            53: Forth primitive 'dup'
        !            54: 
        !            55:        dup ( a -- a a) \ Duplicate top of stack element
        !            56: 
        !            57: 
        !            58: prim.in:       
        !            59:        cod(DUP)
        !            60: 
        !            61: prim.code:
        !            62:        PRIM(DUP) cell x = TOS; PUSH; TOS = x; MIRP
        !            63: 
        !            64: Generated code:
        !            65: 
        !            66: static cell xt_DUP[] = { { .a = xt_DOTICK }, { .c = "\000\003DUP" },
        !            67:         { .a = &&code_DUP }, };
        !            68: 
        !            69: code_DUP: { asm("#### " "DUP"); void *w = (cfa = (++ip)->a)->a;
        !            70:         cell x = (*dp); dp++; (*dp) = x; goto *w; }
        !            71: 
        !            72: Without going into detail, it can be seen, that the data stack is
        !            73: implemented in C as an array of cells, where dp is the pointer to the top of
        !            74: stack. 
        !            75: 
        !            76: For the implementation of the Open Firmware, most of the
        !            77: code is added as Forth code and bound to the engine.  Also 
        !            78: the system vector for reset and all kinds of exceptions
        !            79: will be part of the image. Additionally a secondary boot-loader
        !            80: or any other client application can be bound to the code as payload, 
        !            81: e.g. diagnostics and test programs.
        !            82: 
        !            83: The Open Firmware image will be put together by the build 
        !            84: process, with a loader at the start of the image. This loader
        !            85: is called by Low Level Firmware and loads at boot time the Open 
        !            86: Firmware to it's location in memory (see 1.3 Load process). Additionally 
        !            87: a secondary boot loader or any other client application can be bound
        !            88: to the code as payload.
        !            89: 
        !            90: The Low Level Firmware (LLFW) is responsible for setting up the 
        !            91: system in an initial state. This task includes the setup of the 
        !            92: CPUs, the system memory and all the buses as well as the serial port
        !            93: itself.
        !            94: 
        !            95: 
        !            96: 2.0 Extension
        !            97: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
        !            98: 
        !            99: In the following paragraphs it will be shown how to add
        !           100: new primitive words (i.e., words implemented not by building
        !           101: pre-existing Forth words together, but instead implemented in
        !           102: C or assembler).  With this, it is possible to adapt SLOF to
        !           103: the specific needs of different hardware and architectures.
        !           104: 
        !           105: 
        !           106: To add primitives:
        !           107:    
        !           108:    For a new primitive, following steps have to be done:
        !           109: 
        !           110:    + Definition of primitive name in <arch>.in
        !           111:      - cod(ABC) defines primitive ABC
        !           112: 
        !           113:      You can also use the following in a .in file, see existing
        !           114:      code for how to use these:
        !           115:      - con(ABC) defines constant ABC   
        !           116:      - col(ABC) defines colon definition ABC
        !           117:      - dfr(ABC) defines defer definition ABC
        !           118: 
        !           119:    + Definition of the primitives effects in <arch>.code
        !           120:      - PRIM(ABC) ... MIRP
        !           121: 
        !           122:        The code for the primitive body is any C-code. With
        !           123:        the macros of prim.code the data and return stack of 
        !           124:        the Forth engine can be appropriately manipulated.
        !           125: 
        !           126: 
        !           127: 3.0 Limitations of this package
        !           128: ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
        !           129: 
        !           130:  On a JS20 the memory setup is very static and therefore there are
        !           131:  only very few combinations of memory DIMM placement actually work.
        !           132: 
        !           133:  Known booting configurations:
        !           134: 
        !           135:     * 4x 256 MB (filling all slots) -- only "0.5 GB" reported.
        !           136:     * 2x 1 GB, slots 3/4 -- only "0.5 GB" reported.
        !           137: 
        !           138:  Known failing configurations
        !           139: 
        !           140:     * 2x 256 MB, slots 3/4
        !           141:     * 2x 256 MB, slots 1/2
        !           142: 
        !           143:  On a JS20 SLOF wil always report 0.5 GB even if there is much more memory
        !           144:  available.
        !           145: 
        !           146:  On a JS21 all memory configurations should work.
        !           147: 
        !           148: Documentation
        !           149: +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
        !           150: 
        !           151: [1] IEEE 1275-1994 Standard, Standard for Boot (Initialization Configuration)
        !           152:     Firmware: Core Requierements and Practices
        !           153: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.