Consistent identification of the simulator release
This is a proposal for accommodating dps8 issue #30 (closed) (about the dps8m simulator displaying a user-friendly release number on the console when first invoked) and the related concern about having one consistent way of identifying a particular release of the simulator and having that identification used everywhere.
Layout of information in PROM
Bytes 0-50: As described in section 3.13 of MULTICS DIFFERENCES MANUAL DPS 8 70/M (58009997-040). In particular, there is a Date-Ship Code field in bytes 26-33 with the format YYYYMMDD, in which we are placing the Commit date of the simulator build.
Byte 60: layout_version number
NUL = Only PROM bytes 0-49 are populated, as described in MULTICS DIFFERENCES MANUAL DPS 8 70/M. This is also indicated by bytes 26-33 being less than 20200101.
“1” = the version that is described below.
“2" … “9” left for future layouts (hopefully upwards-compatible).
Bytes 80-82: The major release number as three ASCII digits including leading zeros
Bytes 83-85: The minor release number as three ASCII digits including leading zeros
Bytes 86-88: The patch number as three ASCII digits including leading zeros
Bytes 89-91: The iteration number as three ASCII digits including leading zeros. If this is a general release, this field should contain three ASCII zeros. The first iteration of an Alpha test release, a Beta test release, a release candidate, or a development release is "001" and the number is incremented by 1 for each successive iteration.
Byte 100: The Release Type character as follows:
A: Alpha release
B: Beta release
C: Release candidate
D: Development release
R: General Release
X: "Built from source" with no GIT environment, so we don't know what is intended
Other values of the Release Type character are reserved for future use.
Release Types A, B, C, D, and R are determined from GIT tags. When a tarball/zip file is being prepared, the Release Type is set to X, since we don't know how it will be used - however the iteration number in PROM bytes 89-91 and the type of iteration and the iteration number appearing at the end of the textual string representation of the version number in PROM bytes 101-127 will be the same as in the associated GIT build.
GIT tags should include the following without the square brackets:
-alpha[number] to indicate an alpha test release
-beta[number] to indicate a beta test release
-rc[number] to indicate a release candidate
-dev[number] to indicate a development release
in each case, number is the iteration number (which is also stored in PROM bytes 89-91. The above tags should always include the iteration number. The first iteration is 1 and the iteration number is incremented by 1 for each successive iteration. It is an error to use one of the above iteration tags without an iteration number. If that error occurs, if possible it will be handled as though the iteration number were 1.
Bytes 101-127: The release number in the exact textual form to be displayed. It consists of three required components with Period delimiters and, if the iteration number is greater than zero, a fourth component. It is padded on the right with Space characters. The layout is as follows:
- The major release number, with leading zeros compressed out.
- An ASCII Period ("." = 56 octal).
- The minor release number, with leading zeros compressed out.
- An ASCII Period ("." = 56 octal).
- The patch number, with leading zeros compressed out.
- Depending on the Release Type character (in byte 100) as follows. Where number is called out it is the leading zero suppressed iteration number. The square brackets around number are not included.
- For R (a general release): Pad with ASCII Space characters through byte 127
- For A (an Alpha test release): -alpha[number]
- For B (a Beta test release): -beta[number]
- For C (a Release candidate): -rc[number]
- For D (a Development release): -dev[number]
- Padding with ASCII Space characters through byte 127.
Bytes 130-149: The description of the architecture on which this simulator is intended to be run (as determined at build time), padded with ASCII Space characters through byte 149.
Bytes 150-169: The description of the operating system on which this simulator is intended to be run (as determined at build time), padded with ASCII Space characters through byte 169.
Quoting Gary Dixon "The dps8-developers of today should ... coalesce all references to particular dps8 software into the chosen mechanism. I am aware of several such references:
- The detailed GIT references to dps8 on a particular branch, with components selected by a specific GIT commit ID.
- The dps8 console log announcement message emitted each time dps8 is bootloaded.
- The Rn.n identifier tied to particular pre-built dps8 executables announced in the Multics-wiki update instructions.
- The dps8 PROM shipped_date information (static so far in all released versions of dps8, but changing in some of the upcoming dps8 versions). This PROM shipped date is visible in the Multics syserr log messages giving PROM information each time Multics is booted, or when a CPU is added to a running system.
"All of these versions should be using the same naming scheme, and should be based on whatever data is used to assign a version identifier in GIT and announce that version number when a particular dps8 executable is used."
This proposal includes the ship date field containing the most recent commit date for the build, a release type character, a release number with three or four components (see the above description of bytes 101-127), and additional information (defined in the above descriptions of bytes 130-169).
Since we want the information to be presented identically in all media and all geographic locations, we don't want any adjustments for differences between the time zone where the build was made and where the simulator is being run.
All characters stored in the PROM should be either an ASCII NUL character or an ASCII graphic character, 040 - 176 octal. (It is understood that earlier versions of the dps8 simulator didn't explicitly set PROM bytes 51 and above, so those bytes will be NUL and can be ignored if the ship date (PROM bytes 26-33) is earlier than 20200101.)
The date of the most recent commit in the current build should be stored in PROM bytes 26-33 as eight ASCII digits formatted as YYYYMMDD. It will always be the date of the commit for that build, independent of what kind of a release is being built. It should be announced each time dps8 is bootloaded.