/* ES40 emulator. * Copyright (C) 2007-2008 by the ES40 Emulator Project * * Website: http://es40.org * E-mail : camiel@es40.org * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * * This program 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 General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA * 02110-1301, USA. * * Although this is not required, the author would appreciate being * notified of, and receiving any modifications you may make to the * source code that might serve the general public. */ /** * \file * Contains extra comments for Doxygen. * * You could read the documentation from this file; but it would probably * be easier to go to http://es40.sourceforge.net. * * $Id$ **/ /** * \mainpage ES40 Emulator Documentation * * \section intro Introduction * Welcome to the documentation for the ES40 Emulator Project. For the * main project page, goto http://es40.org. * * On these pages here, you can find the documented source code, the change * log, and more. **/ /** * \page faq Frequently Asked Questions * Here, you can find the answers to a few frequently asked questions. * * \section a A. Compilation * Compilation related issues. * * \subsection a1 A1. SDL not found * Q: I get warnings about SDL.H, sdl.lib, sdlmain.lib or sdl.dll not being * found. What do I need? * * A: You need the Simple DirectMedia Layer (SDL) libraries, if you want to * use one of the emulated VGA cards. Visit http://www.libsdl.org. To run * the emulator you need the runtime libraries, to compile the emulator you * need the development libraries. Make sure your compiler/linker can find * the header and library files. * * \subsection a2 A2. SDL not available * Q: SDL is not available for my system, or I don't want to install it. * What are my options? * * A: Compile without HAVE_SDL defined. For Windows, you can download the * no_sdl version of the binary package. If you're on Windows, change the * configuration file (gui=win32), if your system supports X-Windows (as is * the case on most Linux/BSD/UNIX distributions, change it to gui=X11. * If your system is not supported, remove the gui section alltogether, as * well as any vga-card sections. Graphics support will not be available * in this case. * * \subsection a3 A3. PCAP not found * Q: I get warnings about pcap.h, wpcap.lib, wpcap.dll, or libpcap not being * found. What do I need? * * A: You need the libpcap (Linux and others) or winpcap (Windows) packet * capture libraries, if you want to use one of the emulated network cards. * Visit http://www.tcpdump.org or http://www.winpcap.org. To run the emulator * you need the runtime libraries, to compile the emulator you need the * developer's pack. Make sure your compiler/linker can find the header and * library files. * * \subsection a4 A4. PCAP not available * Q: PCAP is not available for my system, or I don't want to install it. * What are my options? * * A: Your only option is to disable network support, by compiling without * HAVE_PCAP defined. For Windows, you can download the no_net version of * the binary package. * * \subsection a5 A5. Endianess issues * Q: I'm running the ES40 emulator on a big endian host machine (PowerPC, * Sparc) and I get all these strange errors. Network, graphics and disks * don't seem to work properly. * * A: Support for big-endian host architectures has been available in the * past, but since the primary developer of the ES40 Emulator no longer * has a big endian machine, it has become difficult to support and * maintain. If you can, please help us get the emulator working on big- * endian architectures again! * * \section b B. Configuration * Configuration related issues. * * \subsection b1 B1. Which VGA card? * Q: Which of the two emulated VGA cards should I choose? S3 Trio64 or * Cirrus? * * A: Short answer: That depends on what the OS you intend to run on the * emulator likes. Long answer: Right now, both cards are nearly identical * (except for the PCI configuration ID, which tells the OS what card this * is). In the future, the emulated Cirrus card may evolve into a more * complete card, supporting various SVGA features. For the S3 Trio, this * is more difficult, because documentation is harder to find. Since * DECwindows on OpenVMS doesn't seem to like either of the cards, support * for an entirely different card may be added in the future. */ /** * \page cons Consulted Documentation * The following documents have been useful to us: * - Alpha 21264/EV68CB and 21264/EV68DC Microprocessor Hardware Reference Manual [HRM] (http://download.majix.org/dec/21264ev68cb_ev68dc_hrm.pdf) * - DS-0026A-TE: Alpha 21264B Microprocessor Hardware Reference Manual [HRM] (http://ftp.digital.com/pub/Digital/info/semiconductor/literature/21264hrm.pdf) * - Alpha Architecture Handbook [AHB] (http://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf) * - Alpha Architecture Reference Manual, fourth edition [ARM] (http://download.majix.org/dec/alpha_arch_ref.pdf) * - Tsunami/Typhoon 21272 Chipset Hardware Reference Manual [HRM] (http://download.majix.org/dec/tsunami_typhoon_21272_hrm.pdf) * - AlphaServer ES40 and AlphaStation ES40 Service Guide [SG] (http://www.dec-store.com/PD_00158.aspx) * - 21143 PCI/Cardbus 10/100Mb/s Ethernet LAN Controller Hardware Reference Manual [HRM] (http://download.intel.com/design/network/manuals/27807401.pdf) * - AT Attachment with Packet Interface - 5 (ATA/ATAPI-5) (http://www.t13.org/Documents/UploadedDocuments/project/d1321r3-ATA-ATAPI-5.pdf) * - Programming Interface for Bus Master IDE COntroller (http://suif.stanford.edu/%7Ecsapuntz/specs/idems100.ps) * - FDC37C669 PC 98/99 Compliant Super I/O Floppy Disk Controller (http://www.smsc.com/main/datasheets/37c669.pdf) * - SCSI 2 (http://www.t10.org/ftp/t10/drafts/s2/s2-r10l.pdf) * - SCSI 3 Multimedia Commands (MMC) (http://www.t10.org/ftp/t10/drafts/mmc/mmc-r10a.pdf) * - SYM53C895 PCI-Ultra2 SCSI I/O Processor (http://www.datasheet4u.com/html/S/Y/M/SYM53C895_LSILogic.pdf.html) * - SYM53C810A PCI-SCSI I/O Processor (http://ftp.netbsd.org/pub/NetBSD/arch/bebox/doc/810a.pdf) * - Symbios SCSI SCRIPTS Processors Programming Guide (http://la.causeuse.org/hauke/macbsd/symbios_53cXXX_doc/lsilogic-53cXXX-scripts.pdf) * - Ali M1543C B1 South Bridge Version 1.20 (http://mds.gotdns.com/sensors/docs/ali/1543dScb1-120.pdf) * - VGADOC4b (http://home.worldonline.dk/~finth/) * . **/ /** * \page guest_os Guest OS Notes * * Status for various guest OSes under ES40 * * \section hp DEC/Compaq/HP OS-es * * \subsection vms OpenVMS * Test 8.3 * - Using newide, all devices are recognized and use DMA mode, including CDs. * - There is a permissions violation during install. Do not abort it, and the * install will work anyway. (note Camiel: differing results of installation * reported. A lot seems to depend on timing). * . * * \subsection tru64 Tru64 Unix * Tested using 5.1B * - Using the newide device: * - Devices are probed correctly. * - DMA is supported. * - installs and configures. * - es40 system too hot? remove your dpr.rom and restart! * . * - Using the ali_ide device * - devices timeout on probe. * . * . * * \section free Free OS'es * * \subsection fbsd FreeBSD * Tested with 6.2 * - Using newide * - devices are probed and DMA is used. * - CD-ROM device works, but occasionally times out. * . * . * * \subsection nbsd NetBSD * Tested 3.1.1 * - Panics if cirrus device is present. * - Using newide * - all devices are recognized and use DMA mode. * - CD-ROM devices are supported and work for install and normal use * . * - Using ali_ide * - all devices are recognized and pio mode is used. * - CD-ROM devices are not supported * . * . * * Tested 4.0 * - Panics if cirrus device is present. * - Using newide * - recognizes all devices and uses DMA * - CD-ROM cannot be used due to apparent cdrom corruption. * . * - Using ali_ide * - Unknown at this time. * . * . * * \subsection obsd OpenBSD * Tested 4.2 * - Crashes immediately upon boot. * . * * \subsection linux Linux * Tested using Debian 4.0 rc 0, centos 4.2, gentoo 2007.0. * Always boot with "boot -flags 1" when using a serial console. * - Gentoo + ali_ide: hang after hda size display * - Gentoo + newide: hang after hda size display * - Centos: hangs after serial probe. * - Debian: hangs after serial probe. * . * * \section srm SRM * Ok, its not really an OS, but it acts like one. * - Can boot CDROMs with newide device (with cdrom=true) * - Cannot boot CDROMs with ali_ide device (segfault) * . * When booting CDROM-type media with the ali_ide device, * set the disk is cdrom=false. **/ /** * \page build_guide Building and Installation Guide * * \section unix UNIX, BSD and Linux * These instructions are valid for most UNIX-like operating systems, including BSD and * Linux variants. * * \subsection unix_pr Prerequisites * The following prerequisites are required: * - A bourne shell (/bin/sh) that is capable of running the supplied configure script. * - The GNU C++ compiler or another supported C++ compiler. * - The make program. * - The Poco C++ libraries, version 1.3.2 or higher. * . * * \subsection unix_bi Building and Installation * - Download the ES40 Emulator sources. * - Extract the source tree to a clean directory. * - Run the configure script, and answer the questions asked. * - Run make. * - Run make install * . * \code * $ ./configure * $ make * $ make install * \endcode * * \section vms OpenVMS * These instructions are for building the ES40 Emulator on OpenVMS Alpha and OpenVMS * Itanium. * * \subsection vms_pr Prerequisites * The following prerequisites are required: * - The DEC C++ compiler (CXX). * - GNV version 2.1 (get this from the HP site, the Sourceforge site is no longer * kept up-to-date. * . * * \subsection vms_b Building * - Download the ES40 Emulator sources. * - Extract the source tree to a clean directory. * - Run the make_vms script, and answer the questions asked. * . * \code * $ @MAKE_VMS.COM * \endcode * * \section win Microsoft Windows * These instructions are for building the ES40 Emulator on Microsoft Windows. * * \subsection win_pr Prerequisites * The following prerequisites are required: * - Microsoft Visual C++ 2005 or higher. * - The Poco C++ libraries, version 1.3.2 or higher. * . * * \subsection win_b Building * - Download the ES40 Emulator sources. * - Extract the source tree to a clean directory. * - Go to the directory src/build_win* that matches your Visual C++ version, * and processor-word-size (32 or 64 bit) of your Windows version, and open * the project file found there. * - Build the configurations you need. * . **/ /** * \page dev_guide Developer's Guide * On this page, people who want to contribute can find information. * * This page is a work in progress. * * \section d_dev Devices * The emulator consists of classes that emulate different devices that are part * of a real ES40 system. * * \subsection d_dev_thr Threading * Some devices may need - or want - to perform certain activities in a different thread * than the main execution thread. This needs to be done in a platform-independant manner, * and for that purpose we are using the Threading part of the Poco-library * (http://pocoproject.org/). * * When multi-threading an application, one should think about the following: * - Efficiency of the thread. Don't let the thread run when there is no work to do. * - Handling exceptions that occur in the thread. * - Properly ending the thread when the emulator exits. * - Protect data-structures that are used across threads. * . * * Threading code * * Add the following include files to the header-file for the class: * \code * #include * #include * #include * #include * \endcode * * The device class should publicly inherit the Poco::Runnable class. * * The following data members should be added to the class: * \code * Poco::Thread myThread; * Poco::Semaphore mySemaphore; * bool StopThread; * \endcode * * The class also needs a method run, that performs the work that * needs to run in the separate thread: * \code * void ::run() * { * try * { * for(;;) * { * mySemaphore.wait(); // main thread will set the semaphore * // when work needs to be done, or if * // the thread needs to terminate. * if (StopThread) * return; // main thread has signalled us that * // we need to terminate. * * < work >; // do work as long as work needs to be * // done. * } * } * catch(...) {} // if an exception occurs, catch it and * // terminate. The main thread will see * // that this thread has terminated, and * // throw a new exception. * } * \endcode * * mySemaphore and myThread need to be added to the initializer list on * the class constructor: * \code * ... , mySemaphore(0,1), myThread("") * \endcode * * The thread is started from the constructor: * \code * StopThread = false; * myThread.start(*this); * \endcode * * Whenever there is work that the thread needs to do, the thread is * signalled with the following code: * \code * mySemaphore.set(); * \endcode * * The thread should be shut down from the class' destructor: * \code * StopThread = true; * mySemaphore.set(); // signal the thread to end * myThread.join(); // wait for the thread to end * \endcode * * To catch unexpected termination of a thread due to an exception, * the status of the thread is checked periodically (from DoClock): * \code * if(!myThread.isRunning()) * FAILURE("thread has died"); * \endcode * * If data structures need to be accessed by multiple threads, it may * be necessary to protect these structures by a Mutex. These mutexes * are class members of type Poco::Mutex, for instance: * \code * Poco::Mutex myLock; * \endcode * * The access to the data structures is then surrounded by a lock/unlock * construction: * \code * myLock::lock(); * ; * myLock::unlock(); * \endcode **/