Readme.txt for Darkstar v1.1.9.0:
Darkstar provides emulation of the Xerox Dandelion workstation, commonly known as the Star, 8010, or 1108.
To avoid confusion in the rest of this document, the name "Star" will be used to refer to any of the above machines.
Darkstar currently emulates the following Star hardware:
- Standard 8010/1108 Central Processor (CP) with 4KW of microcode store
- i8085-based IO Processor (IOP)
- Up to 768KW of main memory
- Bitmapped Display
- Keyboard / Mouse
- 10, 40, or 80mb hard drives (SA1000 interface)
- 8 inch floppy drive
- 10mbit Ethernet
- Real-time clock
- Keyboard beeper
At this time, the below are not emulated by Darkstar:
- Serial ports
- The LSEP printer interface
Darkstar will run on any Windows PC running Windows Vista or later, with version 4.5.3 or later of the .NET Framework installed. .NET should be present by default on Windows Vista and later; if it is not installed on your computer it can be obtained at https://www.microsoft.com/net.
Darkstar will also run under Mono (http://www.mono-project.com/) on Unix platforms. macOS support will be present in a future release. SDL 2.0 is used for the emulated display -- use your operating system's package manager to ensure this is installed.
The Star keyboard has many keys not present on modern keyboards. Many of these are mapped to Function keys, arrow keys, and the Home/End/PgUp/PgDown keys present on most desktop keyboards -- laptop keyboards may be more difficult to use, depending on your keyboard's layout.
A three-button mouse is useful for using some Star software (XDE and Interlisp-D, for example). On most mice, the mousewheel can be clicked to provide the third (middle) button. Laptops with trackpads may have configuration options to simulate three buttons but will likely be clumsy to use.
If you wish to make use of the emulated Star's Ethernet interface, you
will need to have WinPCAP installed (on Windows) or libpcap (on the Unix of
your choice). WinPCAP can be downloaded from http://www.winpcap.org/.
Using the Ethernet interface allows to access services on the network through
the protocols supported by the guest operating system running in Darkstar. These
can be TCP/IP based services like an FTP server or XNS (Xerox Network System)
services. Real Xerox XNS server installations are rather seldom today, so
using an XNS emulation like Dodo (see https://github.com/devhawala/dodo for
setup and configuration details) may be an alternative for building up a virtual
Xerox machines network.
If only Dodo emulated XNS services are to be accessed from Darkstar, a direct
connection to the Dodo NetHub can be configured instead of using a pcap device
for accessing a real network.
Installation of Darkstar on Windows is simple: Double-click the installer file, named "DarkstarSetup.msi" and follow the on-screen instructions. The installer will install all of the necessary files and create two icons on your Start menu, one for Darkstar itself, and one for its documentation (the file you're reading now!)
On Unix platforms, extract the Darkstar-mono.zip archive in a directory of your choosing.
On Windows, Darkstar can be started by clicking on the "Darkstar" icon created by the installer. On Unix, Darkstar can be started from a shell prompt by running "mono Darkstar.exe" in the directory chosen in Section 3.0.
Once started, the main Darkstar window will appear. This window is your primary means of interaction with the emulated Star workstation.
The large (initially black) area is the Star's display. Clicking anywhere in this area while the Star system is running will "capture" the mouse and keyboard: your mouse movements and keyboard inputs will be sent to the Star, and mouse movements will be restricted to the Darkstar window. To release the capture, press either "Alt" key on your keyboard.
At the bottom of the Darkstar window is the Status Bar. This shows information about the system. From left to right:
-
The current MP (Maintenance Panel) code. On a real Star, this is a 4 digit LED display on the front of the CPU unit. The number displayed is used to communicate boot status and diagnostic information to the user. If the display reads "----" this indicates that the Star has turned the MP display off or it has not been initialized. A comprehensive list of MP codes can be found on Bitsavers at http://bitsavers.org/pdf/xerox/8010_dandelion/Dandelion_MPCodes_Mar85.pdf.
-
The System status: Stopped or Running.
-
The Emulation speed: In fields per second and as a percentage of a real Star's execution speed. 78 fields/sec is approximately 100%.
-
Mouse Capture status: Indicates whether the mouse is currently captured.
The System menu allows you to control the Star system and the emulator. The items in the menu are enumerated below.
Start / Stop - This will start the Star system running if it is stopped, and stop it if it is already running.
Reset - This will reset the Star. This is equivalent to pressing the "B Reset" button on a real Star.
Alternate Boot - Allows selection of an alternate boot device. On a real Star,
this is accomplished by holding down the Alt Boot button during
power-up until the appropriate code appears in the MP display.
Selecting a device in this menu will simulate holding the Alt Boot
button as appropriate to select the boot device.
In general you won't need to change this unless you are installing or
performing maintenance on an operating system. However: Selecting
"Rigid" rather than the default ("DiagnosticRigid") can save time
when booting ViewPoint or XDE.
Floppy Disk - Allows loading or unloading of floppy disk images. If an image is currently loaded, its name will be displayed in the space at the bottom of the submenu; hovering over this space will show the full path to the image and image metadata, if present. Darkstar uses floppy disk images in ImageDisk (.IMD) format. See: http://www.classiccmp.org/dunfield/img/index.htm for details.
Hard Disk - Allows loading or creating new hard disk images, which typically have a ".IMG" file extension. If an image is currently loaded, its name will be displayed in the space at the bottom of the submenu; hovering over this space will show the full path to the image. See Section 10.0 for information on the image format.
Configuration - Invokes the Configuration dialog. See Section 4.0 for more details on configuration options.
Full Screen - Toggles Full Screen mode, in this mode the Star's display will expand to fill the screen. Press Ctrl+Shift+F to exit Full Screen mode.
Show Debugger - Invokes the Debugger interface. See section 5.0 for more details on care and feeding.
Exit - Quits Darkstar. Contents of loaded hard disk images are saved to the image files they were loaded from.
The Star's keyboard has many keys that are not present on a standard PC keyboard. Darkstar maps F1-F12, the arrow keys, and the home/end/pgup/pgdown keys to these special keys, as below:
| Star Key | PC Key |
|---|---|
| Again | F1 |
| Delete | F2 |
| Find | F3 |
| Copy | F4 |
| Same | F5 |
| Move | F6 |
| Open | F7 or Left Control |
| Props | F8 or Right Control |
| Center | F9 |
| Bold | F10 |
| Italics | F11 |
| Underline | F12 |
| Superscript | Print Screen |
| Subscript | Scroll Lock |
| Larger/Smaller | Pause |
| Defaults | Num Lock |
| Skip/Next | Home |
| Undo | Page Up |
| Defn/Expand | End |
| Stop | Page Down |
| Help | Up Arrow |
| Margins | Left Arrow |
| Font | Backslash |
| Keyboard | Down |
Darkstar does not come with any media. Bitsavers has floppy disk sets for ViewPoint, XDE, and Interlisp-D at:
http://bitsavers.org/bits/Xerox/8010/ and http://bitsavers.org/bits/Xerox/1108/
These can be used to bootstrap a fresh installation onto a virtual hard disk. Note that at this time, only floppy disk images in ImageDisk format (.IMD) are supported by Darkstar.
Pre-built hard disk images suitable for use with Darkstar are available at:
http://bitsavers.org/bits/Xerox/8010/8010_hd_images.zip
Documentation for the above operating systems is available at:
http://bitsavers.org/pdf/xerox/viewpoint http://bitsavers.org/pdf/xerox/interlisp-d/ and http://bitsavers.org/pdf/xerox/xde/
If you have an existing hard disk image, you can boot from it by first loading the image using the "System->Hard Disk->Load..." menu. This will present a file dialog allowing you to select the image to load.
After the image is loaded, use the "System->Start" menu to start the Star running. During boot, the MP code displayed in the lower-left corner of the window will display various values indicating status, or in the cases of failure, a diagnostic code.
ViewPoint and XDE will run a lengthy set of diagnostics during boot -- these can be skipped by selecting "Rigid" from the "System->Alternate Boot" menu before starting or restarting the Star.
Covering the proper installation and maintenance of the various Star operating systems is beyond the scope of this manual, but a few poorly documented and emulator-specific bits of advice are provided here.
In general, the manuals listed in Section 3.3.1 are the best starting point and are not too difficult to understand.
To boot from an OS installation or diagnostic floppy, load the appropriate floppy disk image using the "System->Floppy Disk->Load..." menu. Then select the "Floppy" Alternate Boot item from the "System->Alternate Boot" menu and start or reset the emulated Star system. The system should then boot from the floppy disk.
When starting the installation of a new operating system from scratch, there are a few steps that are not well documented and which are fairly unintuitive:
-
In general it is useful to have the time and date set in the Star's TOD clock before booting. Many Star operating systems and installers really want to know what time it is, and they don't trust you to type it in. If the TOD has an invalid time / date it will attempt to get it from the network and in many cases will not proceed until the network responds. Unless you have an XNS timeserver running on your network (you probably do not), use the Configuration dialog to set the time before booting (See section 4.0).
-
If you are starting with a new unformatted hard disk the installer will hang waiting for the disk microcode to read the disk, usually after printing the initial banner ("Installer Version X.Y of DD-MMM-YY HH:MM:SS, etc."). It will sit here indefinitely.
To get past this, you will need to boot the Diagnostic floppy (usually provided with each set of installation floppies) and use the diagnostics to format the disk. This is still more complicated than it should be due to the way the disk microcode interacts with an unformatted disk. After booting the diagnostic floppy you will be prompted to enter timezone and time / date information.
After entering this information, the diagnostic will print something similar to:
XX Megabyte Storage Diagnostic Program 8.0 of 11-Mar-88 11:16:45 PST
>Fault AnalysisAnd then it will pause for 30-45 seconds and fail with:
Fatal error: Microcode.After which the system halts and will not respond to input.
This is because the Fault Analysis step is expecting a formatted disk and your disk is not yet formatted. The disk microcode is unable to cope and goes off into the weeds.
To work around this, when the
>Fault Analysisline appears during boot, hit the "Stop" key on the Star's keyboard (this is mapped to "Page Down.") The diagnostic will print:
<STOP> key acknowledgedCommand stoppedAnd leave you at the ">" prompt. Now you can format your disk!
Or can you? Typing a "?" will give you a list of available commands but there's nothing related to disk formatting in that list!
Xerox didn't want the average person to be able to format disks so this functionality is hidden by default. To enable it, you use the Logon command -- Type "Logon" and hit return, and it will ask you for a user name. Use "Xerox" and then provide the password "wizard" (or "elf", depending on your stature.) Your privileges will be upgraded and now "?" will reveal a host of fun commands! The "Format" command is what you want, and is mostly self-explanatory. Do not save the bad page table (as there isn't one, and the microcode will hang trying to read it.) Formatting will take several minutes after which you will be asked if you want to recreate the bad page table (say "yes."). You will given the option to do a media scan (you can if you want, but emulated disks have no bad spots so there isn't much point.)
Once the disk has been formatted, you can boot the Installer disk and go about doing the actual installation.
-
Yes, it really does take ViewPoint 10-15 minutes to boot the first time. It's not particularly swift on subsequent boots, either. Patience is a virtue when using a Star.
-
If you get stuck at MP Code 937 during boot, first try the advice in (1) above. Setting dates post-Y2K may cause issues with some operating systems. On Viewpoint you might also want to install the Set Time utility (see the official Viewpoint docs and installer help for details).
-
The default startup diagnostics that run during Viewpoint or XDE boot may fail the RTC test (with flashing MP code 0323 / 0007). This occurs if the emulated Star is not running at 100% speed -- either because Throttling is off (See Section 4.1) or because your computer isn't capable of running the emulation at full speed. This is because the emulated Star is running faster or slower than the test expects relative to the RTC -- the test thinks that the RTC is behaving incorrectly. In these cases, you can either (1) Enable Throttling during boot (if the system is running too fast) or (2) use the "System->Alternate Boot" menu to select "Rigid" rather than "Default" -- this will bypass startup diagnostics entirely.
The following passwords will allow you to run Viewpoint in perpetuity. When using them, ensure the emulated Star's TOD clock is set to a date in December, 1997 (afterwards the clock can be set to whatever date you like):
ViewPoint 1.1 / Services 10.0: J SH9R JX2A CH3N
ViewPoint 2.0 / Services 11.0: 8 7T78 M8YL LFEQ
Darkstar's configuration dialog can be invoked with the "System->Configuration..." menu. This is a small window with multiple tabs. Each tab is explained in detail in the following subsections.
The System Configuration tab provides configuration for three options:
-
Memory Size (KW): Configures the amount of memory installed in the system, From 128KW to 768KW in 128KW increments. This defaults to 768KW.
Changes made here will not take effect until the system is reset. -
Host ID (MAC Address): Configures the Star's Ethernet MAC Address (also used as the system's Host ID for licensing.) If you have multiple instances of the emulator running on the same network, all instances should have unique MAC addresses, and you'll also want to make sure that no other real devices on your network have the same MAC address. Note that changing this on systems running Viewpoint will likely invalidate any previously entered product factoring (license) keys.
-
Throttle Execution Speed: Checking this box will limit execution speed to the execution speed of a real Star. When unchecked, the emulation will run as fast as the host processor allows. Note: See Section 3.3.3 for potential pitfalls with this option disabled.
The Ethernet Configuration tab allows the selection of the host network interface
to use with Darkstar. The listbox for the available interfaces contains at least
the entries None (for no ethernet adapter) and [[ Dodo-Nethub ]] (for a direct
connection to a Dodo NetHub). If WinPcap or libpcap
is available, further network interfaces will be listed.
If the [[ Dodo-Nethub ]] entry is selected, the 2 input fields for the NetHub
Host and Port will be activated for specifying the destination NetHub.
The Display Configuration tab provides options for the emulated Star's display:
-
Slow Phosphor Simulation: If checked, the slow phosphor of a real Star's display is simulated. This is not necessary for any real purpose but looks more authentic and incurs no performance penalty.
-
Display Scale: Allows scaling the display by a factor 1, 2, 3 or 4. This is useful on 4k (or higher) resolution displays with a high DPI.
-
Stretch screen in Fullscreen mode: Stretches the Star's display to fill the entire screen in fullscreen mode. This maintains the original display's aspect ratio. Depending on the resolution of the screen, this may result in a blurry display.
The Time Configuration tab provides options for initializing the Star's TOD (time of day) clock at the time the emulation is started or reset. This is primarily useful to aid in working around the absence of XNS time servers, the lack of which can cause problems with some Star operating systems.
There are three options for TOD clock initialization:
-
Current time/date: This sets the Star's TOD to the current time/date with no adjustments or changes.
-
Current time/date with Y2K compensation: This sets the Star's TOD to the current time/date with 28 years subtracted from the date. This works around software that's not Y2K compliant while still allowing the calendar to match up.
-
Specified time/date: This sets the TOD to a specific time and date. This is useful for working around Viewpoint product factoring (license) key expiry.
-
Specified date: This sets the TOD to the specified date, using the current (real) time. This is useful as above, but allows the Star's clock to be in sync with reality.
-
No change: This leaves the TOD alone at powerup/reset. Use this if you plan to set the time manually or via XNS, or if you want to maintain the current time / date across resets.
Darkstar has an integrated debugger that can make use of microcode and IOP (8085) source code (if available) to aid in debugging. The debugger can be invoked via the "System->Show Debugger" menu.
This debugger is extremely crude, and is not user-friendly at all.
The debugger consists of three windows -- the Console, the CP Debugger, and the IOP debugger. Commands can be executed in the Console window, and sources, disassembly and breakpoints can be viewed in the CP and IOP debugger windows.
The "?" or "help" command at the Console window will give you a brief synopsis of the various commands at your disposal.
The Darkstar program accepts the following optional command line parameters:
-
-configconfigurationFile
specify the configuration file (see below) defining the presets for the configuration to be used (these presets can be overriden using the configuration dialog) -
-rompathpath
specify the path where the ROM files are located -
-start
start the emulator when the UI is ready, this requires that the disk image to be used is defined (either through the configuration file or by the Windows defaults)
(on the Windows platform, these parameters can be given either on the command line prompt or can be included in the program invocation line specified for a reference icon)
Using configuration files simplifies using several Star machines, each consisting of a hard disk image file with the required presettings, each defined by a specific machine configuration file.
The configuration file is a text file with "parameter = value" lines
for setting configuration values; empty lines and lines starting with
a hash character are ignored.
The following configuration parameters can be given, matching the corresponding entries in the configuration dialog or the system menu:
-
MemorySize =nnn
system memory size, in KWords as decimal value. -
HardDriveImage =filename
filename for the hard disk image to load -
FloppyDriveImage =filename
filename for the floppy disk image to load -
HostID =12-hex-digits
the Ethernet host address for this machine, given as hexadecimal number for the 48 bit machine id -
HostPacketInterfaceName =device
the name of the Ethernet adaptor on the emulator host to use for Ethernet emulation, one of:None,[[ Dodo-Nethub ]]or any network adapter listed in the configuration dialog (as recognized by WinPcap or libpcap, if present) -
ThrottleSpeed =boolean
whether to cap execution speed at native execution speed or not -
DisplayScale =n
scale factor to apply to the display -
FullScreenStretch =boolean
whether to apply linear or nearest-neighbor filtering to the display, when scaled -
SlowPhosphor =boolean
whether to apply a fake "slow phosphor" persistence to the emulated display -
TODSetMode =mode
how to set the TOD clock at power up/reset, one of:
HostTimeY2K, HostTime, SpecificDateAndTime, SpecificDate, NoChange -
TODDateTime =iso-datetime
the specific date/time to set the TOD clock to if TODSetMode is "SpecificDateAndTime" -
TODDate =iso-date
the specific date to set the TOD clock to if TODSetMode is "SpecificDate" -
AltBootMode =mode
the preferred Alt-Boot mode for starting the machine, one of: None, DiagnosticRigid, Rigid, Floppy, Ethernet, DiagnosticEthernet, DiagnosticFloppy, AlternateEthernet, DiagnosticTrident1, DiagnosticTrident2, DiagnosticTrident3, HeadCleaning -
Start =boolean
start the system when the UI is ready? (default: false)
- Speed throttling is not implemented on Unix platforms.
- SDL is forced to software-rendering mode on Unix platformst due to an odd bug that has yet to be solved. Performance may suffer as a result.
If you believe you have found a new issue (or have a feature request) please send an e-mail to [email protected] or open an issue on the GitHub site (see Section 8.0)
When you send a report, please be as specific and detailed as possible:
- What issue are you seeing?
- What software are you running?
- What operating system are you running Darkstar on?
- What are the exact steps needed to reproduce the issue?
The more detailed the bug report, the more possible it is for me to track down the cause.
The complete source code is available under the BSD license on GitHub at:
https://github.com/livingcomputermuseum/Darkstar
Contributions are welcome!
The Star's hard drive controller is implemented in microcode and controls the drive at a very low level, so the hard drive image format is not simply a dump of the sector data on the disk.
The image consists of a single byte header which indicates the type of SA1000 disk the image contains data for:
1 - Shugart SA1004 (10MB)
2 - Quantum Q2040 (40MB)
3 - Quantum Q2080 (80MB)
All other values are currently invalid. The geometry for the above disks are:
SA1004 - 256 cylinders, 4 heads (or tracks)
Q2040 - 512 cylinders, 8 heads
Q2080 - 1172 cylinders, 7 heads
Following the header are multiple 5325 word blocks, one for each track on the disk, starting at cylinder 0, head 0, followed by cylinder 0, track 1 and so on. Each word in the disk image is 24 bits wide, written in little-endian order: The most significant 8 bits indicate the type of data in the word, the low 16 bits are the data word itself:
0 - Disk data or unused
1 - Address mark (for header, label, or data)
2 - CRC
The Star's controller divides each track into 16 sectors; each sector consists of three fields: Header, Label, and Data. Each of these begins with an Address Mark - 0x1a141 for the Header, 0x1a143 for the Label and Data. Each of the fields end with two words of CRC (currently always a dummy value of 0x2beef).
Xerox specified that the Header is two 16-bit words in length, the Label is 12 words, and the Data field is 256 words. However: As the writing of address marks, data, and CRC are controlled by microcode (which could potentially vary between revisions of the operating system) it is probably best not to make assumptions about the positioning and length of the sectors. If you need to extract data, parse each track, looking for the address marks and CRCs to delineate the actual data.
Darkstar would not have been possible without the amazing preservation work of Bitsavers.org
Ethernet encapsulation is provided courtesy of SharpPcap, a WinPcap/LibPcap wrapper. See: https://github.com/chmorgan/sharppcap.
Display rendering and keyboard/mouse input is provided through SDL 2.0, see: https://www.libsdl.org/ and is accessed using the SDL2-CS wrapper, see: https://github.com/flibitijibibo/SDL2-CS.
- new network device for direct connection to a Dodo NetHub
- new optional command line parameter "-start" (start system when the UI is up)
- new parameters in configuration-file to match relevant UI items
- fix to Ethernet device for receiving packets larger than 56 bytes
- fix to configuration-dialog to permit 48 significant bits for Host ID
- fix to display for border pattern lines
- added StarOS 5.0 disk image (including configuration file) to Disks subdirectory
- Floppies can now be formatted and written.
- Tweak to "No change" time configuration option (sets Power Loss flag.)
- Added full screen display mode
- Fixed Ethernet receiver; Ethernet controller now works reliably.
- Cleaned up shutdown code, made hard disk image saving more robust in the face of failure
- Removed 1MW memory option since it was never a shipping configuration and causes issues with various Xerox software.
Initial release.