From uucp Mon Nov  3 14:51:51 1986
>From hpfclr!hpiholx!wmf  Mon Nov  3 14:08:07 1986 remote from hpfcla
Received: by hpfcla ; Mon, 3 Nov 86 14:08:07 mst
Date: Mon, 3 Nov 86 14:08:07 mst
From: hpfcla!hpfclr!hpiholx!wmf
Message-Id: <8611032108.AA27868@hpfcla>
Received: from hpfclr with uucp; Mon, 3 Nov 86 13:51:22
Received: from hpiholx with uucp; Mon, 3 Nov 86 13:44 MST
To: hpfclr!fpfcla!mcatee, hpfclr!hpfcla!drw, hpfclr!hpfcla!george,
        hpfclr!hpfcla!jones, hpfclr!hpfcla!meh, hpfclr!hpfcla!rob,
        hpfclr!hpfcla!wmf
Subject: Stable Store initialization (SS_init) program ERS (Please review!)
Status: R

   What follows is my ERS for the stable store program "SS_init". I got your
names from a source who thought you might care to make some comments, or at
least might be interested in what is happening. If you have no comments that's
fine. If you don't respond at all I will remove you from the addressee list.
-------------------------------  cut here  -----------------------------------






           Firefox Stable Store Initialization Program ERS

                             Version 0.2



                             Bill Freund

                        Hewlett-Packard Company
                  Colorado Integrated Circuits Division
                        Fort Collins, Colorado





Warning:  HARD HAT AREA!!  This document is still under construction.
                           Look out for falling topics. 




Distribution
    Rev 0.2:  For initial review & comments.
              hpfcla!drw       - CICD R&D
              hpfcla!george    - FSD  MDE
              hpfcla!jones     - FSD  MDE
              hpfcla!mcatee    - IHO
              hpfcla!meh       - IHO
              hpfcla!rob       - IHO
              hpfcla!wmf       - CICD R&D - Author



















1. Introduction

   This manual describes the Firefox stable store initialization ("SS_init")
program. This manual includes a user's guide to its operation, and a detailed
description for use by people assigned to modify the code. Aside of the source
code itself, no other document exists which describes what SS_init is or what
it does.

   Stable Store ("SS") is a programmable, yet non-volatile type of memory which
is used on the Firefox system to retain important system parameters on a perm-
anent basis. SS_init will be the program used by Manufacturing to initialize
the contents of stable store in newly constructed systems to the original
'factory installed' values.

2. Overview

   To better understand this topic area, I think a brief overview of how the
program (SS_init) operates, and what the stable store memory contains, may
be useful:

2.1 The SS_init program

   When called, SS_init starts by reading a user provided configuration file
"SS_init_conf" which contains stable store related data that changes very
infrequently (like the model and revision numbers for the hardware).

   SS_init next reads the stable store itself, and holds it in memory. If SS
contains some preliminary data (like the on board clock's frequency) it will
be retained for re-use. If it is determined that SS has never been properly
initialized, all of SS will then be written with zeroes.

   The operator is next provided the opportunity to make changes to system
specific data (like the clock calibration data). If the operator elects to
change a data field, the existing data will be provided (if appropriate), so
the user need not re-enter good data. All user inputs are reviewed to assure
that the data conforms to a 'legal' format for the particular input.

   As a result of all of the above operations, an image of what stable store
should look like is created. The data is presented to the operator to cross-
check, and if accepted, the SS is written with the desired data. Only those
SS locations actually requiring changes will be written, the rest are left
untouched.

   If SS is updated, it will re-read and compared to the intended contents to
ensure that the intended changes did indeed get inserted. A failure will result
in a message to the operator.

   When SS_init has completed operations it will return to to the "ISL>"
prompt.

2.2 How Stable Store is organized

   The stable store is divided into four equally sized areas which I shall
call 'quadrants':

   The first two quadrants are architected, and have their contents defined
by Chapter 5 of reference (2). These quadrants should be identical, using
redundancy to assure that valid data will survive in the event of a power
failure (or other catastrophe) while modifying one of the two quadrants.
Information contained in this area will include primary and secondary boot
paths.

   The third quadrant is non-architected, and contains data as defined in
reference (3). This includes a smorgasbord of system specific data, including
a unique system identification number and calibration data for the on board
clock.

   The fourth quadrant will contain checksum information for the first three
quadrants, which will be used to assure that data read from the SS is correct.

   Maintenance of the duplicate second quadrant and the checksum area is user-
transparent when stable store is accessed via the system call 'pdc_stable'.
This procedure updates the checksum whenever data is written to SS, and
confirms (via the checksum) that valid data is available whenever data is read
from SS.  This call is documented in chapter 3 of reference (2).

   More specific details as to data locations and formats may be found in
Appendix 'A' of this document.

3. The User's Guide

   Or, everything you needed to know in order to use this program, plus a few
more details.

3.1 Environment

   The stable store initialization program (SS_init) will reside in the
Diagnostic User Interface (DUI) environment, and may be run when the "ISL>"
prompt is seen by simply typing "SS_init".

3.2 Operation

   SS_init program needs to have another file present, which it reads in order
to obtain information which changes very infrequently. A file named
'SS_init_conf' should exist, and contain data in the order and format as given
in Appendix 'B' of this document. Without this file you will not be able to
proceed.

   When the program is called it will ask questions about whether you want to
change some entries:
   (1) The system clock calibration data;
   (2) The hardware ID number;
   (3) The boot and console paths; and finally,
   (4) Whether the program has gotten all of your inputs correctly.

   If you elect to enter (new) clock calibration data, the input will be in the
form of a decimal number "xxxxx.xxx".  That is: nine digits long, including
three digits after the decimal point.
   
   If you elect to enter a (new) hardware ID number, it will be in the form of
a decimal number between 0 and 9999999999.  That is: one to ten digits long,
each digit a number between 0 and 9.

   You must select one option for boot and console paths from the menu. Simply
choose the menu item number (1, 2, ...) that is appropriate.

   If you are happy with the summary of data to be entered answer Y(es) to
program the stable store, answer N(o) and then fix what you don't like, or
answer Q(uit) to leave the stable store unchanged.

   If you have entered the data correctly and allowed the program to proceed,
it will update the stable store and re-read stable store to confirm that it got
the changes. If the update failed, a message to that regard will be provided
and the program will return to the last ("Do you agree with this data") prompt.
A good check will allow the program to exit to the "ISL>" prompt. The program
has completed its run at this point.

4. Hardware Set

   The anticipated manufacturing environment in which SS_init will operate
will be a Firefox connected to a CS-80 disc via a CIO HP-IB card. The disc will
contain (among other things) a copy of the SS_init program, linked to DUI and
ISL. The Firefox will also be connected to a system console via a CIO 6-channel
MUX.

5. References:

   ** Under Construction **

   (1) Firefox System board ERS
      - Rob Horning

   (2) SPECTRUM System Initialization Architecture

   (3) SPECTRUM ???
      - Lists information in non-architected area of SS (Steve McAtee?)

   (4) Firefox Turn-on Test (first pass description)
      - George Winski e-mail memo 8610242148.AA02846@hpfcla





                Appendix 'A': Stable Store contents
                ===================================

   As defined in reference (1), stable store is located in the address range
0xf0040000 - 0xf005ffff. It is accessible in single byte amounts, one byte for
every 4 bytes of address space. The two LSBs are not used, and should be left
word-aligned ('00'). Data is transferred in bits 24..31 of the word.

   Stable Store on the Firefox consists of 2 Kbytes of EEPROM memory. With the
the 17 (less the 2 LSB) bit address space (32 Kbyte) available, this memory is
aliased several times over. On an unaliased basis, the 2 Kbytes are accessible
over the range 0xf0040000 to 0xf0041fff.

   Independent of the size of the stable store, it will be subdivided into four
equally sized 'quadrants' which will have data formats as given below. The data
for each quadrant will start at the quadrant's starting address, and take as
much memory as is required to contain the data. The rest of the quadrant is
simply unused.

   ** Under Construction **

   Quadrants #1 and #2 represent an architected area of stable store, and are
formatted as follows:
   96 bytes:
      - 32 bytes: Primary boot path
      - 32 bytes: Unique file names
      - 32 bytes: Future OS requirements
                  - 2 bytes: SSVERSION
   In an optionally architected area of SS:
   96 bytes:
      - 32 bytes: Console I/O path
      - 32 bytes: Alternate boot path
      -
   References:  See Chapter 5 of reference (2) for the architected quadrants.

   Quadrant #3 represents an un-architected area of stable store and is
formatted as follows:

      -  4 bytes: HW_ID (32 bit unique identifier)
      -  4 bytes: SW_ID (same number as HW_ID)
      -    bytes: SVERSION (set to model: 00000004   rev: 01)
      -    bytes: HVERSION (set to model: 008        rev:  0)
      -  4 bytes: BOOT_ID (same number as HW_ID)
      -    bytes: SW_CAP (set to all 0's)
      -    bytes: CVERSION (??)

   References:  See reference (3) for the unarchitected quadrant.

   Quadrant #4, as noted before, is considered to be a private domain under
exclusive control of the 'pdc_stable' call. Its format is considered to be a
concern only to pdc_stable, and hence will not be discussed here.

   References:  The 'pdc_IRS' and source code for 'pdc_stable'.
                See Steve McAtee for details.





        Appendix 'B':  Data format for the "SS_init_conf" file.
        =======================================================

   ** Under Construction **

   This file specifies the data order and format to be followed in making a
configuration file ......... of the commonly used data.

   This file may be assembled using any editor. It simply must be in the
correct format so that when data is read from it, that the data is jammed into
the correct data slots.

////////////////////////////
   Other (Appendix) Topics ??
   ? Performance                            (I don't think this is an issue)
   ? Maintainability                        (What would I say?)
   ? Commands implemented?
   ? Hazards
   ? Error messages & how to deal with them (Do I really need these?)
   ? Functional Block Description           (Do I need this?)
///////////////////////////////////////////////

                                                    hpiholx: /users/wmf/ers/ers




