Emulator: Difference between revisions

From Uzebox Wiki
Jump to navigation Jump to search
No edit summary
mNo edit summary
(36 intermediate revisions by 7 users not shown)
Line 1: Line 1:
==Description==
==Description==
Uzebox has its own emulator called '''Uzem'''. You can use it for both kernel and games development.
Uzebox has its own emulator called '''Uzem'''. You can use it for both kernel and games development. It was originally developed by David Etherton.
 
There is also an emulator based on the softgun simulator for more information see http://softgun.sourceforge.net/uzebox.shtml.


'''Features:'''
'''Features:'''
*Multi-platform (Linux, Windows and MacOS)
*Multi-platform (Linux, Windows and MacOS)
*Implements the CPU atmega644 used by Uzebox
*Implements Atmega644 CPU and peripherals used by Uzebox
*Video and Sound using [www.libsdl.org/ SDL]
*Video and Sound using [www.libsdl.org/ SDL2]
*Mouse (Uzebox supports SNES mouse)
*Joystick and mouse support
*SDCard (for the Gameloader)
*Emulates SNES gamepads, SNES mouse, and PS/2 keyboard
*GDB Server
*SDCard (writing not yet supported)
*GDB Server (For debugging)
*Elapsed cycle profiler
*Captures/playback gamepads data to/from file
*Realtime movie recording (requires [https://www.ffmpeg.org/download.html FFMPEG] intalled)
 
There is other emulators available: Softgun simulator and more recently [http://mamedev.org/release.html MAME (0.162)] (After the merge with the MESS sub-project). The current version of Softgun has some issues with the keymap, the mouse is emulate with keys and the monitor is accessed by VNC. For more details, see: http://softgun.sourceforge.net/uzebox.shtml
 
'''Usage:'''
uzem [OPTIONS] GAMEFILE
 
 
'''Command line options:'''
 
--help -h          Show this help screen
--nosound  -n      Disable sound playback
--fullscreen -f    Enable full screen
--swrenderer -w    Use SDL software renderer (probably faster on older computers
--novsync -v        Disables VSYNC (does not apply to software renderer
--mouse -m          Start with emulated mouse enabled
--2p -2            Start with snes 2p mode enabled
--sd -s <path>      Specify a content path for the SD card emulation. If not specified, it mounts the directory in which the .HEX/.UZE resides.
--eeprom -e <file>  Use following filename for EEPRROM data (default is eeprom.bin)
--boot -b          Bootloader mode.  Changes start address to 0xF000
--gdbserver -d      Debug mode. Start the built-in gdb support
--port -t <port>    Port used by gdb (default 1284)
--capture -c        Captures gamepads data to file (GAMEFILE.cap)
--loadcap -l        Load and replays controllers data from capture file
--synchelp -z      Displays and logs information to help troubleshooting HSYNC timing issues
--record -r        Record a movie in mp4/720p(60fps) format. (ffmpeg executable must be in the same directory as uzem or in the system path)
 
 
'''Keyboard control:'''
F1  Display help
F5  Debugger resume execution (if compiled with DISAM switch)
F9  Debugger halt execution (if compiled with DISAM switch)
F10  Debugger single step (if compiled with DISAM switch)
0    AVCORE Baseboard power switch
1/2  Adjust left edge lock
3/4  Adjust top edge lock
5    Toggle NES/SNES 1p/SNES 2p/SNES mouse mode (default is SNES pad)
6    Mouse sensitivity scale factor
7    Re-map joystick
Esc  Quit emulator
            Up Down Left Right A B X Y Start Sel LShldr RShldr
NES:        ----arrow keys---- a s    Enter Tab             
SNES 1p:    ----arrow keys---- a s x z Enter Tab LShift RShift
  2p P1:    w  s    a    d  f g r t  z    x    q      e 
  2p P2:    i  k    j    l  ; ' p [  n    m    u      o
 
==Download==
Pre-compiled versions:
* Windows: http://uzebox.org/downloads/uzem_win32-v2.0.0.zip


==Building==
==Building==


===Prerequisites===
===Pre-requisites===
*GCC compiler and SDL
*GCC compiler and SDL2 libraries
**Windows: Download them from http://www.mingw.org/ and http://www.libsdl.org
**Windows: Download them from http://www.mingw.org/ (Download the installer) and http://www.libsdl.org (Download the *development* libraries)
**Linux:
**Linux:
***Ubuntu: sudo apt-get install build-essential  libsdl1.2-dev
***Ubuntu: sudo apt-get install build-essential  libsdl1.2-dev
Line 22: Line 73:
***Fedora: yum install gcc gcc-c++ SDL-devel
***Fedora: yum install gcc gcc-c++ SDL-devel
**Mac OS X: Download them from [http://connect.apple.com Xcode] and http://www.libsdl.org
**Mac OS X: Download them from [http://connect.apple.com Xcode] and http://www.libsdl.org
===Install===
====Windows====
*Install mingw in the default location: c:\MinGW
*Install the core files and MSYS (important in order to use make)
*Add C:\MinGW\bin and C:\MinGW\msys\1.0\bin to your system's path
*Add C:\WinAVR\utils\bin to your system's path (you will need Unix style of mkdir and rm)
*Create folder C:\MinGW\includes\SDL and copy all SDL include files in there
*Copy SDL library files to C:\MinGW\lib (i.e: libSDLmain.a etc)
*Copy SDL2.dll into C:\MinGW\bin


===Download===
===Download===
Get the last Uzebox version from http://code.google.com/p/uzebox/
Get the lastest Uzem sources from Github at https://github.com/Uzebox/uzebox/tree/master/tools/uzem
 
'''Note:''' If you are going to download from the SVN server, the current development tree is the branch '''rev_beta5'''


===Compiling===
===Compiling===
Line 36: Line 95:
This process will create two executables: uzem and uzemdbg.<br>
This process will create two executables: uzem and uzemdbg.<br>
Important: The uzemdbg is only used for the Emulator development, it generates a lot of debugging messages and is very slow.
Important: The uzemdbg is only used for the Emulator development, it generates a lot of debugging messages and is very slow.


==Using==
==Using==
Line 43: Line 101:
To see all the options available run: '''uzem --help'''  
To see all the options available run: '''uzem --help'''  


==Profiling==
The emulator can be used to help optimize code speed. It does so by using the WDR assembly instruction before and after the code to be profiled and output the cycles elapsed in the console. In C, import <avr/wdt.h> and use wdt_reset() before/after the code to profile.


==GDB==
==GDB==
Uzem implements an internal GDB server (originally based on [http://savannah.nongnu.org/projects/simulavr/ simulavr]) making it an important tool to develop Uzebox games.
Uzem implements an internal GDB server (originally based on [http://savannah.nongnu.org/projects/simulavr/ simulavr]) making it an important tool to develop Uzebox games.
===Running Uzem in debug mode===


The following examples are using the game Arkanoid.<br>
The following examples are using the game Arkanoid.<br>
Line 54: Line 116:
<code><pre>
<code><pre>
$ uzem -d  ../../demos/Arkanoid/default/Arkanoid.hex
$ uzem -d  ../../demos/Arkanoid/default/Arkanoid.hex
NOTE THIS IS AN EXPERIMENTAL BRANCH OF THE UZEBOX EMULATOR
PLEASE SEE THE FORUM FOR MORE DETAILS:  http://uzebox.org/forums


Loading Hex Image...
Loading Hex Image...
Line 64: Line 123:
Uzem will start and wait for the GDB client to connect.
Uzem will start and wait for the GDB client to connect.


===avr-gdb===
===Gdb clients===
 
Now with Uzem running in debug mode, you need the gdb client to debug the game. Following is a list of GDB clients and front-ends you can use.
 
====avr-gdb====


----
----
Line 78: Line 141:
Windows: It is shipped with WinAvr
Windows: It is shipped with WinAvr
Linux: Check you distribution.
Linux: Check you distribution.
*Ubuntu has the avr-gdb package but its version (6.4) has some issues about variables in flash and will crash.
*Ubuntu 9.10 provides the avr-gdb package but its version (6.4) has some issues about variables in flash and will crash.


If you want compile the last version visit http://www.nongnu.org/avr-libc/user-manual/install_tools.html for more details.
If you want compile the last version visit http://www.nongnu.org/avr-libc/user-manual/install_tools.html for more details.
Line 108: Line 171:
Use the option '''-x''' like: '''avr-gsb -x gdb-script.cfg Arkanoid.elf'''
Use the option '''-x''' like: '''avr-gsb -x gdb-script.cfg Arkanoid.elf'''


===KDbg===
====avr-insight====
 
----
 
{{GdbClient:
|Name=avr-insight
|OS=Windows, Linux and MacOS
|Site=http://sourceware.org/insight/
|Type=Gui
}}
avr-insight is a GUI with avr-gdb embedded. For windows users, it is distributed in the WinAVR tool suite and can be started and connected to an already running Uzem like so:
 
'''avr-insight -x gdb-script.cfg Arkanoid.elf'''
 
====KDbg====


----
----
Line 139: Line 216:


The KDbg is running and connected. It is very intuitive, on the bottom you have Stack and Breakpoints and on the right variables and expressions to inspect data. From the menu option ''View'' you see Registers and Memory.
The KDbg is running and connected. It is very intuitive, on the bottom you have Stack and Breakpoints and on the right variables and expressions to inspect data. From the menu option ''View'' you see Registers and Memory.
====Eclipse====
----
{{GdbClient:
|Name=eclipse
|OS=Windows, Linux and MacOS
|Site=http://www.eclipse.org
|Type=Gui
}}
If you want to use Eclipse for AVR development, you may find the [http://avr-eclipse.sourceforge.net AVR Eclipse Plugin] useful.<br>
For directions about debugging in Eclipse with Uzem and GDB, see [http://uzebox.org/wiki/index.php?title=Uzebox_Developement_Under_Eclipse#Debugging this page].
===Gdb Problems===
====Starting a debug session with 'steps'.====
If you connect to your target and try to step, you may get some errors or gdb will even crash. This happens because gdb client is trying to read an invalid address from SRAM. To avoid this, use a breakpoint into main() (or other function you want) and give a 'continue'.<br>
Filipe's note: It looks like an GDB bug, but I'm getting more details before submit a bug report.
====Variables in flash (PROGMEM)====
The debugger says a variable defined with PROGMEM is 'out of bounds' and will shows it with a SRAM address (over 0x800000).
Gdb can get the variable value, so it knows the variable is in flash, but if you get the variable address and try to overwrite it, GDB thinks it is in SRAM. If you want the real flash address, just subtract 0x800000. If you want overwrite a value, use the gdb command '''set {type} addr = value'''.<br>
Example using the global variable ''const char strEnd2[] PROGMEM = "THAT WAS THE LAST LEVEL"'' declared in Arkanoid.c:
<code><pre>
(gdb) print strEnd2
$3 = "THAT WAS THE LAST LEVEL"
(gdb) print strEnd2[0]=64
Cannot access memory at address 0x80a003
(gdb) print &strEnd2
$4 = (char (*)[24]) 0x80a003
(gdb) set {char}0xa003 = 64
(gdb) print strEnd2
$5 = "@HAT WAS THE LAST LEVEL"
</pre></code>
Filipe's note: Again this looks like a GDB bug. I tried change types like 'char *' to 'prog_char *' but gdb still get crazy. I will send a bug report as soon I get finished more tests.


==FAQ==
==FAQ==

Revision as of 22:44, 15 April 2016

Description

Uzebox has its own emulator called Uzem. You can use it for both kernel and games development. It was originally developed by David Etherton.

Features:

  • Multi-platform (Linux, Windows and MacOS)
  • Implements Atmega644 CPU and peripherals used by Uzebox
  • Video and Sound using [www.libsdl.org/ SDL2]
  • Joystick and mouse support
  • Emulates SNES gamepads, SNES mouse, and PS/2 keyboard
  • SDCard (writing not yet supported)
  • GDB Server (For debugging)
  • Elapsed cycle profiler
  • Captures/playback gamepads data to/from file
  • Realtime movie recording (requires FFMPEG intalled)

There is other emulators available: Softgun simulator and more recently MAME (0.162) (After the merge with the MESS sub-project). The current version of Softgun has some issues with the keymap, the mouse is emulate with keys and the monitor is accessed by VNC. For more details, see: http://softgun.sourceforge.net/uzebox.shtml

Usage:

uzem [OPTIONS] GAMEFILE


Command line options:

--help -h           Show this help screen
--nosound  -n       Disable sound playback
--fullscreen -f     Enable full screen
--swrenderer -w     Use SDL software renderer (probably faster on older computers
--novsync -v        Disables VSYNC (does not apply to software renderer
--mouse -m          Start with emulated mouse enabled
--2p -2             Start with snes 2p mode enabled
--sd -s <path>      Specify a content path for the SD card emulation. If not specified, it mounts the directory in which the .HEX/.UZE resides.
--eeprom -e <file>  Use following filename for EEPRROM data (default is eeprom.bin)
--boot -b           Bootloader mode.  Changes start address to 0xF000
--gdbserver -d      Debug mode. Start the built-in gdb support
--port -t <port>    Port used by gdb (default 1284)
--capture -c        Captures gamepads data to file (GAMEFILE.cap)
--loadcap -l        Load and replays controllers data from capture file
--synchelp -z       Displays and logs information to help troubleshooting HSYNC timing issues
--record -r         Record a movie in mp4/720p(60fps) format. (ffmpeg executable must be in the same directory as uzem or in the system path)


Keyboard control:

F1   Display help
F5   Debugger resume execution (if compiled with DISAM switch)
F9   Debugger halt execution (if compiled with DISAM switch)
F10  Debugger single step (if compiled with DISAM switch)
0    AVCORE Baseboard power switch
1/2  Adjust left edge lock
3/4  Adjust top edge lock
5    Toggle NES/SNES 1p/SNES 2p/SNES mouse mode (default is SNES pad)
6    Mouse sensitivity scale factor
7    Re-map joystick
Esc  Quit emulator

            Up Down Left Right A B X Y Start Sel LShldr RShldr
NES:        ----arrow keys---- a s     Enter Tab              
SNES 1p:    ----arrow keys---- a s x z Enter Tab LShift RShift
  2p P1:     w   s    a    d   f g r t   z    x     q      e  
  2p P2:     i   k    j    l   ; ' p [   n    m     u      o

Download

Pre-compiled versions:

Building

Pre-requisites

  • GCC compiler and SDL2 libraries
    • Windows: Download them from http://www.mingw.org/ (Download the installer) and http://www.libsdl.org (Download the *development* libraries)
    • Linux:
      • Ubuntu: sudo apt-get install build-essential libsdl1.2-dev
      • OpenSuse: sudo zypper install -t pattern devel_C_C++ SDL-devel
      • Fedora: yum install gcc gcc-c++ SDL-devel
    • Mac OS X: Download them from Xcode and http://www.libsdl.org

Install

Windows

  • Install mingw in the default location: c:\MinGW
  • Install the core files and MSYS (important in order to use make)
  • Add C:\MinGW\bin and C:\MinGW\msys\1.0\bin to your system's path
  • Add C:\WinAVR\utils\bin to your system's path (you will need Unix style of mkdir and rm)
  • Create folder C:\MinGW\includes\SDL and copy all SDL include files in there
  • Copy SDL library files to C:\MinGW\lib (i.e: libSDLmain.a etc)
  • Copy SDL2.dll into C:\MinGW\bin

Download

Get the lastest Uzem sources from Github at https://github.com/Uzebox/uzebox/tree/master/tools/uzem

Compiling

  • Unpack it
  • Open a command line terminal, go to the tools/emulator/ directory
  • To see the available options, type make help
  • Type make for the default options

This process will create two executables: uzem and uzemdbg.
Important: The uzemdbg is only used for the Emulator development, it generates a lot of debugging messages and is very slow.

Using

Just run the emulator in the command line and pass the game (iHex file) as parameter: uzem path/to/your/game.hex

To see all the options available run: uzem --help

Profiling

The emulator can be used to help optimize code speed. It does so by using the WDR assembly instruction before and after the code to be profiled and output the cycles elapsed in the console. In C, import <avr/wdt.h> and use wdt_reset() before/after the code to profile.

GDB

Uzem implements an internal GDB server (originally based on simulavr) making it an important tool to develop Uzebox games.

Running Uzem in debug mode

The following examples are using the game Arkanoid.
Windows users: Don't forget to use backslash "\"

Execute uzem with the option -d and the game file:

$ uzem -d  ../../demos/Arkanoid/default/Arkanoid.hex

Loading Hex Image...
Waiting on port 1284 for gdb client to connect...

Uzem will start and wait for the GDB client to connect.

Gdb clients

Now with Uzem running in debug mode, you need the gdb client to debug the game. Following is a list of GDB clients and front-ends you can use.

avr-gdb


Details
Site: http://sourceware.org/gdb/  
OS: Windows, Linux and MacOS  
Type:    Command line  

This is the official gnu gdb client. Windows: It is shipped with WinAvr Linux: Check you distribution.

  • Ubuntu 9.10 provides the avr-gdb package but its version (6.4) has some issues about variables in flash and will crash.

If you want compile the last version visit http://www.nongnu.org/avr-libc/user-manual/install_tools.html for more details.

Build the game and from the same directory run avr-gdb passing the elf file as parameter:

1. $>cd demos/Arkanoid/default/
2. $>make
3. $>avr-gdb Arkanoid.elf

You will get a prompt like this: (gdb)
Then connect to the Uzem:

4. (gdb)target remote localhost:1284

You don't need to use the GDB command "run". You are already with the debugger session started, but still stopped at the first instruction as you can see:

Remote debugging using localhost:1284
0x00000000 in __vectors ()

Go ahead and start debugging your code.

Refer to GDB manual for more information about the available commands.
GDB cheat sheet: http://www.yolinux.com/TUTORIALS/GDB-Commands.html

Gdb supports script files to automate the tedious task. Arkanoid has a simple script (file: Arkanoid/default/gdb-script.cfg) to connect to the target, insert a breakpoint at main() and continue until it reaches main. Gsb script are text files with gdb commands, but can create new commands using an internal language and others GDB commands.

Use the option -x like: avr-gsb -x gdb-script.cfg Arkanoid.elf

avr-insight


Details
Site: http://sourceware.org/insight/  
OS: Windows, Linux and MacOS  
Type:    Gui  

avr-insight is a GUI with avr-gdb embedded. For windows users, it is distributed in the WinAVR tool suite and can be started and connected to an already running Uzem like so:

avr-insight -x gdb-script.cfg Arkanoid.elf

KDbg


Details
Site: http://www.kdbg.org/  
OS: Linux  
Type:    Gui  

KDbg is a graphical user interface to gdb. It provides an intuitive interface for setting breakpoints, inspecting variables, and stepping through code.

Note: It is a front-end to avr-gdb, so you still need avr-gdb.

To install, user your package manager.

  • Ubuntu: sudo apt-get install kdbg

As you are going to debug an AVR target, you need first configure KDbg to use an avr-gdb:
1. Start KDbg and go to the menu option Settings/Global Options...
2. From the tab Debugger change the option in the box How to invke GDB: from the default gdb to avr-gdb.

  • Make sure your avr-gdb is in the PATH or just use the full path.

There is no option to connect a remote target from KDbg using the GUI interface, so you will need to close it and open from the shell with the option -r:
1. Start uzem with -d
2. Open a new shell
3. $>cd demos/Arkanoid/default/
4. Build if necessary
5. $>kdbg -r localhost:1284 Arkanoid.elf

The KDbg is running and connected. It is very intuitive, on the bottom you have Stack and Breakpoints and on the right variables and expressions to inspect data. From the menu option View you see Registers and Memory.

Eclipse


Details
Site: http://www.eclipse.org  
OS: Windows, Linux and MacOS  
Type:    Gui  


If you want to use Eclipse for AVR development, you may find the AVR Eclipse Plugin useful.

For directions about debugging in Eclipse with Uzem and GDB, see this page.

Gdb Problems

Starting a debug session with 'steps'.

If you connect to your target and try to step, you may get some errors or gdb will even crash. This happens because gdb client is trying to read an invalid address from SRAM. To avoid this, use a breakpoint into main() (or other function you want) and give a 'continue'.
Filipe's note: It looks like an GDB bug, but I'm getting more details before submit a bug report.

Variables in flash (PROGMEM)

The debugger says a variable defined with PROGMEM is 'out of bounds' and will shows it with a SRAM address (over 0x800000). Gdb can get the variable value, so it knows the variable is in flash, but if you get the variable address and try to overwrite it, GDB thinks it is in SRAM. If you want the real flash address, just subtract 0x800000. If you want overwrite a value, use the gdb command set {type} addr = value.
Example using the global variable const char strEnd2[] PROGMEM = "THAT WAS THE LAST LEVEL" declared in Arkanoid.c:

(gdb) print strEnd2
$3 = "THAT WAS THE LAST LEVEL"
(gdb) print strEnd2[0]=64
Cannot access memory at address 0x80a003
(gdb) print &strEnd2
$4 = (char (*)[24]) 0x80a003
(gdb) set {char}0xa003 = 64
(gdb) print strEnd2
$5 = "@HAT WAS THE LAST LEVEL"

Filipe's note: Again this looks like a GDB bug. I tried change types like 'char *' to 'prog_char *' but gdb still get crazy. I will send a bug report as soon I get finished more tests.

FAQ