URL
https://opencores.org/ocsvn/aoocs/aoocs/trunk
Subversion Repositories aoocs
[/] [aoocs/] [trunk/] [doc/] [src/] [documentation.v] - Rev 2
Compare with Previous | Blame | View Log
/* * Copyright 2010, Aleksander Osman, alfik@poczta.fm. All rights reserved. * * Redistribution and use in source and binary forms, with or without modification, are * permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this list of * conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright notice, this list * of conditions and the following disclaimer in the documentation and/or other materials * provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /* This file contains only Doxygen documentation. */ /*! \file documentation.v * \brief aoOCS Doxygen documentation. */ /*! \mainpage * <table border=0 width=100%><tr><td> * The OpenCores aoOCS SoC is a Wishbone compatible implementation of most of the Amiga Original Chip Set (OCS) and computer functionality. * * \author Aleksander Osman, <alfik@poczta.fm> * \date 20.12.2010 * \version 1.0 * </td><td> * \image html ./doc/img/opencores.jpg * </td></tr></table> * * <table border=0 width=100%><tr><td> * <b>Contents:</b> * - <a href="./../../specification.pdf">Specification</a>, automatically generated from: * - \subpage page_spec_revisions * - \subpage page_spec_introduction * - \subpage page_spec_architecture * - \subpage page_spec_operation * - \subpage page_spec_registers * - \subpage page_spec_clocks * - \subpage page_spec_ports * - \subpage page_spec_references * - \subpage page_directory * - \subpage page_notes * - \subpage page_quartus * </td><td> * \image html wishbone_compatible.png * </td></tr></table> * * <b>Structure Diagram:</b> * \image html structure.png * * <b>About the documentation:</b> * The aoOCS core documentation is generated by the Doxygen tool * (www.doxygen.org) with the doxverilog patch * (http://developer.berlios.de/projects/doxverilog/). */ /*! \page page_spec_revisions Revision History * <table width=100%> * <tr style="background: #CCCCCC; font-weight: bold;"> * <td>Rev. </td><td>Date </td><td>Author </td><td>Description </td></tr> * <tr><td>1.0 </td><td>20.12.2010 </td><td>Aleksander Osman </td><td>First Publish </td></tr> * </table> */ /*! \page page_spec_introduction Introduction * * The OpenCores aoOCS SoC is a Wishbone compatible implementation of most of the Amiga Original Chip Set (OCS) and computer functionality. * * aoOCS is not related in any way with Minimig - it is a new and independent Amiga OCS implementation. * * <h3>Features</h3> * - The aoOCS SoC contains the following Amiga/OCS components: * - blitter * - copper * - system control (interrupts) * - video: bitplains, sprites, collision detection * - audio: 4 channels, low-pass filter * - user input: PS/2 mouse, PS/2 keyboard and joystick (keyboard arrow keys) * - floppy: read and write ADF files directly from a SD card. Only the internal floppy drive is implemented * - 8520 CIA * - ao68000 OpenCores IP core is used as the aoOCS processor * - All of the above components are WISHBONE revision B.3 compatible * - The aoOCS contains the following additional components: * - SD card controller written in HDL with DMA. Supports SDHC cards only. * - 10/100 Mbit Ethernet controller written in HDL to send the current VGA frames (frame grabber) * - HDL drivers for SSRAM, PS/2 keyboard, PS/2 mouse, audio codec, VGA DAC * - aoOCS uses only one external memory: a SSRAM with 36-bit words and pipelined access. A video buffer with about 250KB is located SSRAM. Another 256KB are used by the ROM. All the rest memory * can be used as Chip RAM. * - The On-Screen-Display is implemented in HDL as a finite state machine. No additional controller/processor with firmware required to handle the SoC. * - The following options are available on the On-Screen-Display: * - select ROM file to load (only Amiga Kickstart v1.2 was tested) * - enable or disable Joystick (keyboard arrow keys) * - enable or disable floppy write protection * - insert a floppy - select one from a list * - eject an inserted floppy * - reset the system * - The On-Screen-Display is independent of the running Amiga software. It is enabled and disabled by the Home key and controled by the keyboard arrow keys and the right CTRL key. * - Only PAL timings are implemented. * - The video output is VGA compatible: 640x480 at 70 Hz. A rather simple method is used to extend the 256 PAL horizontal lines to 480 VGA lines: all lines are doubled except for every 8th one. * - The system uses generally a single clock: 30 MHz. There are two more clocks: 12 MHz, 25 MHz generated to interface with external hardware (Audio codec, Ethernet controller). A single altpll is used * to generate all three clocks from one 50 MHz external clock. More information about clocks is available at \ref page_spec_clocks. * - A VGA frame grabber is implemented that sends captured frames by 100 Mbit Ethernet in IP/UDP packets. * - The system uses about 26.400 LE on Altera Cyclone II and about 267.000 bits of on-chip RAM. * - The blitter functionality was tested against the E-UAE Amiga software emulator. * - Tested only on a Terasic DE2-70 board (www.terasic.com.tw). * - Documentation generated by Doxygen (www.doxygen.org) with doxverilog patch (http://developer.berlios.de/projects/doxverilog/). The specification * is automatically extracted from the Doxygen HTML output. * * <h3>WISHBONE compatibility</h3> * - Version: WISHBONE specification Revision B.3, * - General description: 32-bit WISHBONE interface, * - WISHBONE data port size: 32-bit, * - Data port granularity: 8-bits, * - Data port maximum operand size: 32-bits, * - Data transfer ordering: BIG ENDIAN, * - Data transfer sequencing: UNDEFINED, * - Constraints on <tt>CLK_I</tt> signal: described in \ref page_spec_clocks. * * <h3>Similar projects</h3> * Other Open-Source Amiga implementations include: * - Minimig (http://code.google.com/p/minimig/) - FPGA-based re-implementation of the original Amiga 500 hardware. Runs on the Minimig PCB and also on Terasic DE1,2 boards. * * <h3>Limitations</h3> * - No filesystem support on the SD card. Data is read from fixed positions. The contents of the SD card is generated by the <tt>aoOCS_tool</tt> described at \ref page_spec_operation. * - No video external synchronize, lace mode, lightpen, genlock audio enable, color composite (BPLCON0) * - All bitplain data is fetched at once in a burst memory read at the begining of each line. No changes to the bitplain data done after the beginning of a line are visible. * - Currently aoOCS requires an 36-bit word SSRAM to store the video buffer. This way 3 pixels 12-bits each can be stored in one word. * - Serial port not implemented. * - Parallel port not implemented. * - Low-pass filter disable/enable by CIA-A port A bit 1 not implemented. * - Proportional controller and light pen not implemented. * - Some rarely used OCS registers are not implemented: strobe video sync, write beam position, coprocessor instruction fetch identify. For a complete list of not implemented * registers look at \ref page_spec_registers. * - Only some of the Amiga software was tested and works on the aoOCS. A list of aoOCS software compatability is located at \ref page_spec_operation. * * <h3>TODO</h3> * - Fix some of the above limitations. * - Optimize the design. * - Run WISHBONE verification models. * - More documentation of Verilog sources. * - Describe testing and changes done in E-UAE sources. * - Prepare scripts for VATS: run_sim -r -> regresion test. * - Port the aoOCS SoC to a Xilinx FPGA. * * <h3>Status</h3> * - Amiga Workbench v1.2 runs with some minor graphic problems: bottom of screen not displayed correctly. * - Prince of Persia runs perfectly. * - Wings of Fury runs correctly. Some sound glitches in intro. * - Lotus 2 runs correctly. Some sound problems in intro. * - Warzone runs poor. Some major graphic problems. * - More information about aoOCS software compatability is available at \ref page_spec_operation. * * <h3>Requirements</h3> * - Altera Quartus II synthesis tool (http://www.altera.com) is required to synthesise the <tt>aoOCS</tt> System-on-Chip. * - Java SDK (http://java.sun.com) is required to compile the <tt>aoOCS_tool</tt> (The tool is described in \ref page_spec_operation). * - A FPGA board. Currently only the Terasic DE2-70 board was tested. * - Icarus Verilog simulator (http://www.icarus.com/eda/verilog/) is required to compile the and run some tests. * - Access to Altera Quartus II directory (directory eda/sim_lib/) is required to compile and run some tests. * - GCC (http://gcc.gnu.org) is required to compile some testes based on E-UAE sources. */ /*! \page page_spec_architecture Architecture * <table border=0 align=center> * <caption> * <b>Figure 1:</b> aoOCS structure. * </caption> <tr><td> * \image html ./doc/img/structure.png * </td></tr></table> * <h1>control_osd</h1> * \copydoc control_osd * * <h1>ao68000</h1> * \copydoc ao68000 * * <h1>ocs_control</h1> * \copydoc ocs_control * * <h1>ocs_blitter</h1> * \copydoc ocs_blitter * * <h1>ocs_copper</h1> * \copydoc ocs_copper * * <h1>ocs_serial</h1> * \copydoc ocs_serial * * <h1>bus_terminator</h1> * \copydoc bus_terminator * * <h1>bus_syscon</h1> * \copydoc bus_syscon * * <h1>ocs_video</h1> * \copydoc ocs_video * * <h1>ocs_audio</h1> * \copydoc ocs_audio * * <h1>ocs_input</h1> * \copydoc ocs_input * * <h1>ocs_floppy</h1> * \copydoc ocs_floppy * * <h1>cia8520</h1> * \copydoc cia8520 * * <h1>drv_vga</h1> * \copydoc drv_vga * * <h1>bus_ssram</h1> * \copydoc bus_ssram * * <h1>drv_audio</h1> * \copydoc drv_audio * * <h1>drv_keyboard</h1> * \copydoc drv_keyboard * * <h1>drv_mouse</h1> * \copydoc drv_mouse * * <h1>drv_debug</h1> * \copydoc drv_debug * * <h1>drv_eth_vga_capture</h1> * \copydoc drv_eth_vga_capture */ /*! \page page_spec_operation Operation * * <h3>SD card</h3> * The aoOCS SoC requires a SD card containing a list of available ROMs and floppy images together with images themselves. The aoOCS does not support any filesystem on the card. * A binary image file must be prepared and written on the card starting at sector 0. The aoOCS_tool is used to prepare the image in the following way: * - a title screen PNG image must be available. A default image is available at \c ./sw/aoOCS_tool/title.png * - a directory with ROM files must be created * - a directory with floppy images (ADF files) must be created * - the following \c make command must be run at the base directory of the project: * \verbatim * make sd_disk AO_INTRO_IMAGE=<path to title screen PNG image> AO_ROMS=<path to ROMs directory> AO_FLOPPIES=<path to floppy images directory> * \endverbatim * - The SD disk image is generated and saved to \c ./tmp/sd_disk.img. That image must be written directly on a SD disk bypassing and most probably destroying the filesystem on the disk. * The easiest way to write the image is to run the \c dd command as a super-user on a Linux system: * \verbatim * dd if=<path to image file> of=<path to SD device> * \endverbatim * * <h3>aoOCS_tool</h3> * The aoOCS_tool is used to: * - Create the contents of the SD card. A image containing: a title screen, ROMs and floppy disk ADF files is created. This image has to be written to the SD * card starting from sector 0. * - Extract vga frames from the drv_eth_vga_capture module as PNG images. * - Generate <tt>./rtl/control_osd.mif</tt> memory initialization file with On-Screen-Display text strings. * - Extract the specification contents from Doxygen HTML output, to generate the specification ODT file. * * The source code for the tool is located at: <tt>./sw/aoOCS_tool/</tt>. * * <h3>On-Screen-Display description</h3> * - After powerup or reset, the SoC tries to initialize the SD card and read the title screen, list of ROM files and list of floppy files. If all goes well, the following screen is displayed: * \image html vga_title.png "aoOCS title screen with ROM selection menu" * * - The On-Screen-Display is controlled by the keyboard arrow Up and Down keys. To select an item use the right Control key: * \image html vga_menu_sel_wb.png "aoOCS floppy selection menu with Amiga Workbench 1.2 floppy highlighted" * * - After selecting the ROM file, the menu disappears and the Amiga boots from the ROM: * \image html vga_kick12.png "Amiga Kickstart v1.2 bootstrap screen" * * - To select a floppy disk to insert into the internal disk drive, the On-Screen-Display is used. To display the menu press the Home key. The Home key is also used to hide the menu. * The menu when no floppy is inserted looks like this: * \image html vga_menu_no_floppy.png "aoOCS floppy selection menu" * * - The following options are available: * - <tt>Joystick (kbd arrows)</tt>: enable or disable the joystick on Amiga port 1. The joystick is controlled by the keyboard arrow keys and the right Control key. When enabled, the * arrow keys are unavailable to the Amiga keyboard - the key strokes are redirected to the joystick. * - <tt>Floppy write enabled</tt>: enable or disable floppy writes. The floppy changes are made directly on the SD disk. * - <tt>Reset</tt>: reset the aoOCS SoC * - Below is a list of available floppy disks to insert. After selecting a floppy the display changes to the following: * \image html vga_menu_floppy_inserted.png "aoOCS menu after floppy selection" * - In this menu it is possible to eject the floppy disk. After ejecting the floppy the previous menu is dispayed. * * <h3>Software compatability list</h3> * The state of software can be: * <table border=0> * <tr><td><i>PERFECT</i> </td><td> no visible and no audible distortions</td></tr> * <tr><td><i>GOOD</i> </td><td> some minor distortions</td></tr> * <tr><td><i>FAIR</i> </td><td> software starts but has major distortions</td></tr> * <tr><td><i>FAILED</i> </td><td> software does not start</td></tr> * </table> * * - Amiga Workbench version 1.2 * <div align="center"><table width="100%"><tr><td width=300> * <table> * <tr><td><b>aoOCS version:</b> </td><td> 1.0 </td></td></tr> * <tr><td><b>State:</b> </td><td><i>GOOD</i> </td></tr> * <tr><td><b>Description:</b> </td><td> * Some minor graphic problems: bottom of screen not displayed correctly. Most probably problem with Copper and vertical beam position. * </td></tr></table> * </td><td> * \image html vga_wb12.png "Amiga Workbench v1.2 screen" * </td></tr></table></div> * * - Prince of Persia * <div align="center"><table width="100%"><tr><td width=300> * <table> * <tr><td><b>aoOCS version:</b> </td><td> 1.0 </td></td></tr> * <tr><td><b>State:</b> </td><td><i>PERFECT</i> </td></tr> * <tr><td><b>Description:</b> </td><td> * No problems. * </td></tr></table> * </td><td> * \image html vga_prince_of_persia.png "Prince of Persia" * </td></tr></table></div> * * - Wings of Fury * <div align="center"><table width="100%"><tr><td width=300> * <table> * <tr><td><b>aoOCS version:</b> </td><td> 1.0 </td></td></tr> * <tr><td><b>State:</b> </td><td><i>GOOD</i> </td></tr> * <tr><td><b>Description:</b> </td><td> * Some sound gliches in introduction. The game itself works perfect. * </td></tr></table> * </td><td> * \image html vga_wings_of_fury.png "Wing of Fury" * </td></tr></table></div> * * - Lotus 2 * <div align="center"><table width="100%"><tr><td width=300> * <table> * <tr><td><b>aoOCS version:</b> </td><td> 1.0 </td></td></tr> * <tr><td><b>State:</b> </td><td><i>GOOD</i> </td></tr> * <tr><td><b>Description:</b> </td><td> * Some minor sound problems in introduction - most probably some bug in the low-pass filter or channel modulation. The VGA frame was captured in the middle of screen update * so there are some distortions. In real-time in looks OK. * </td></tr></table> * </td><td> * \image html vga_lotus2.png "Lotus 2" * </td></tr></table></div> * * - Warzone * <div align="center"><table width="100%"><tr><td width=300> * <table> * <tr><td><b>aoOCS version:</b> </td><td> 1.0 </td></td></tr> * <tr><td><b>State:</b> </td><td><i>FAIR</i> </td></tr> * <tr><td><b>Description:</b> </td><td> * Major graphic problems - as seen on captured VGA frame. * </td></tr></table> * </td><td> * \image html vga_warzone.png "Warzone" * </td></tr></table></div> */ /*! \page page_spec_registers Registers List of not implemented OCS registers: \b ocs_control \verbatim STREQU & *038 S D Strobe for horiz sync with VB and EQU STRVBL & *03A S D Strobe for horiz sync with VB (vert. blank) STRHOR & *03C S DP Strobe for horiz sync STRLONG & *03E S D( E ) Strobe for identification of long horiz. line. VHPOSW *02C W A Write vert and horiz position of beam \endverbatim \b ocs_input \verbatim POT0DAT *012 R P( E ) Pot counter pair 0 data (vert,horiz) POT1DAT *014 R P( E ) Pot counter pair 1 data (vert,horiz) POTGOR *016 R P Pot port data read (formerly POTINP) POTGO *034 W P Pot port data write and start \endverbatim \b ocs_copper \verbatim COPINS 08C W A Coprocessor instruction fetch identify \endverbatim \b ocs_serial \verbatim SERDATR *018 R P Serial port data and status read SERDAT *030 W P Serial port data and stop bits write SERPER *032 W P Serial port period and control \endverbatim \b ocs_floppy \verbatim DSKDATR & *008 ER P Disk data early read (dummy address) \endverbatim \b ocs_blitter \verbatim BLTDDAT & *000 ER A Blitter destination early read (dummy address) \endverbatim */ /*! \page page_spec_clocks Clocks * <table width=100%> * <caption><b>Table 1:</b> List of clocks.</caption> * <tr style="background: #CCCCCC; font-weight: bold;"> * <td rowspan=2>Name</td><td rowspan=2>Source</td><td colspan=3>Rates (MHz)</td><td rowspan=2>Remarks</td><td rowspan=2>Description</td></tr> * <tr style="background: #CCCCCC; font-weight: bold;"> * <td>Max</td><td>Min</td><td>Resolution</td></tr> * * <tr><td>clk_50</td><td>Input Port</td><td>50</td><td>50</td><td>-</td><td>-</td><td>External input clock. Used only as input to altpll.</td></tr> * <tr><td>clk_30</td><td>altpll output</td><td>30</td><td>30</td><td>-</td><td>-</td><td>Main system clock.</td></tr> * <tr><td>clk_12</td><td>altpll output</td><td>12</td><td>12</td><td>-</td><td>-</td><td>Used only in drv_audio to clock the WM8731 audio codec hardware.</td></tr> * <tr><td>clk_25</td><td>altpll output</td><td>25</td><td>25</td><td>-</td><td>-</td><td>Used only in drv_eth_vga_capture to clock the DM9000A Ethernet hardware.</td></tr> * </table> */ /*! \page page_spec_ports IO Ports * <h3>aoOCS top-level IO Ports</h3> \verbatim Inputs Clock and reset clk_50 reset_ext_n DM9000A Ethernet hardware interface enet_irq Switches and hex leds hardware interface from drv_debug debug_sw1_pc debug_sw2_adr debug_sw3_halt Inouts IS61LPS51236A pipelined SSRAM hardware interface ssram_data [35:0] SD bus 1-bit hardware interface sd_cmd_io sd_dat_io PS/2 keyboard hardware interface ps2_kbclk ps2_kbdat PS/2 mouse hardware interface ps2_mouseclk ps2_mousedat WM8731 audio codec hardware interface ac_sdat DM9000A Ethernet hardware interface enet_data [15:0] Outputs IS61LPS51236A pipelined SSRAM hardware interface ssram_address [18:0] ssram_oe_n ssram_writeen_n ssram_byteen_n [3:0] ssram_clk ssram_globalw_n ssram_advance_n ssram_adsp_n ssram_adsc_n ssram_ce1_n ssram_ce2 ssram_ce3_n SD bus 1-bit hardware interface sd_clk_o ADV7123 Video DAC hardware interface vga_r [9:0] vga_g [9:0] vga_b [9:0] vga_blank_n vga_sync_n vga_clock vga_hsync vga_vsync WM8731 audio codec hardware interface ac_sclk ac_xclk ac_bclk ac_dat ac_lr DM9000A Ethernet hardware interface enet_clk_25 enet_reset_n enet_cs_n enet_ior_n enet_iow_n enet_cmd Switches and hex leds hardware interface from drv_debug hex0 [7:0] hex1 [7:0] hex2 [7:0] hex3 [7:0] hex4 [7:0] hex5 [7:0] hex6 [7:0] hex7 [7:0] Leds hardware interface for debug purposes debug_sd [7:0] debug_68k_state [7:0] debug_floppy [7:0] \endverbatim */ /*! \page page_spec_references References * <ol><li> * <em>Specification for the: WISHBONE System-on-Chip (SoC) Interconnection Architecture for Portable IP Cores.</em><br/> * Revision: B.3.<br/> * Released: September 7, 2002.<br/> * Available from: http://www.opencores.org<br/> * </li><li> * <em>Amiga® Hardware Reference Manual.</em><br/> * Revised edition (March 15, 1990)<br/> * Addison Wesley Longman Publishing Co.<br/> * </li><li> * <em>E-UAE Amiga software emulator sources.</em><br/> * Source archive: \c e-uae-0.8.29-WIP4.tar.bz2<br/> * Available from: http://http://www.rcdrummond.net/uae/<br/> * </li><li> * <em>aoOCS Doxygen(Design) Documentation.</em><br/> * </li><li> * <em>ao68000 Doxygen(Design) Documentation.</em><br/> * Available from: http://www.opencores.org<br/> * </li></ol> */ /*! \page page_directory Directory structure * The aoOCS project consists of the following directories: * * \verbinclude ./doc/src/directory.txt */ /*! \page page_notes Design notes * \verbinclude ./doc/src/notes.txt */ /*! \page page_quartus Altera Quartus fit summary * \verbinclude ./doc/src/aoOCS.fit.summary */