Pysix python module

The pysix python module allows a developer to create a python script that runs an sx lst file, sets breakpoints and manipulates the state of the emulator. This can be used to simulate inputs or to log outputs of the SX while it is running its program.

Example

The following code shows some of pysix abilities. It creates an emulator and loads a listing into the emulators ROM. Then it will create a rudimentary LCD display emulator and create two python functions that link the SX output ports to the inputs of the LCD. After all is set up, the script will run the emulator for 100 Mclocks. This should continuously print an updated LCD display.

<source lang="python"> import pysix

1. port definitions

RA = 5 RB = 6 RC = 7

1. create an emulator and load the listing file

sx = pysix.Emulator() listing = pysix.ParseListingFile("../../test/temp_sensor.lst") sx.load_rom( listing)

1. create an lcd 'emulator'

lcd = pysix.CreateDevice( "lcd")

1. port C is directly coupled to lines db0-7 of the lcd, only the upper
2. nibble is communicated, the rest is pulled down to zero.

def PortCChange( addres, value):

   global lcd
   lcd.set_byte_value( "db", value & 0xf0)

1. port B contains the three control lines.

previous_lcd_string = "" def PortBChange( addres, value): global previous_lcd_string lcd.set_bit_value( "rs", value & 0x20) lcd.set_bit_value( "r/!w", value & 0x40) lcd.set_bit_value( "e", value & 0x80)

# if it's a read, simulate the busy flag being reset # there is currently no way to simulate outputs from the lcd device if (value & 0x60) == 0x40: state = sx.state state.ram.set( RC, 0x00) sx.state = state

# ask the lcd for its contents and print them if they have changed. lcd_string = str( lcd) if lcd_string != previous_lcd_string: print "LCD:" print lcd_string previous_lcd_string = lcd_string

1. register events on write to ports

sx.on_memory_write( RC, PortCChange) sx.on_memory_write( RB, PortBChange)

1. run for a short while, 100 000 000 clock cycles.

sx.run( 100000000)

</source>

Pysix classes and functions

ParseListingFile

listing ParseListingFile( fileName) This function opens a listing (.lst) file and parses it. The results will be returned in the form of a listing object.

Listing

This object has no attributes that are visible to python.

SxState

This class represents the state of the simulator. It currently exposes the following attributes:

w

the w register.

m

the m register

pc

the program counter (all 12 bits)

in_interrupt

a boolean that indicates whether the SX is currently handling an interrupt

ram

the ram contents. Access values--both reading and writing--by using sx.state.ram(<address>).

important There is currently an issue that prevents scripts from directly changing the state. This is caused by the fact that sx.state does not return the SX's state itself, but instead returns a copy. So code like the following:

sx.state.w = 0

does not change the value of w on the emulator. What does work (but is cumbersome) is the following

state_copy = sx.state
state_copy.w = 42
sx.state = state_copy

Simulator

The simulator is the central class of the pysix module. It offers the following attributes and functions:

state

SxState. This is the state of the simulator at any given point in time. See #SxState

load_rom( Listing)

boolean. Load the rom with the program bytes specified by the #Listing object. See also ParseListingFile

run( integer)

integer. Will run for the given amount of clock-cycles or until a breakpoint is hit. Will return the amount of cycles left in this run (i.e. it will return zero if no breakpoint was hit and will return n - i if a breakpoint was hit after i cycles).

set_breakpoint( integer)

Sets a breakpoint at the given address. You can reset breakpoints by calling this function with an extra argument:

sx.set_breakpoint( some_address, False)

on_memory_write( address, callback_function)

When the given address is written to by the SX, the given callback will be called with two arguments: the address that was written and the new value:

<source lang="python">

def ShowLedStatus( address, value):
       if value & 0x02 :

sys.stdout.write( "ON \r")

       else:

sys.stdout.write( "OFF\r");

# trigger an action if rb changes		
RB = 0x06		
sx.on_memory_access( RB, ShowLedStatus)

</source>