ports

Documentation

Overview

Package ports represents the input/output parts of the VCS (the IO in RIOT).

Input from "real" devices is handled by HandleEvent() which passes the event to peripherals in the specified PortID.

HandleEvent() should probably no be called directly but instead only through the input package

Emulated peripherals are plugged into the VCS with the Plug() function. Plugging events can be monitored with the plugging.PlugMonitor interface.

Index

• Constants
• type DisablePeripheral
• type Event
• type EventData
• type EventDataPlayback
• type EventDataStick
• type InputEvent
• type NewPeripheral
• type Peripheral
• type PeripheralBus
• type Ports
  • func NewPorts(instance *instance.Instance, riotMem chipbus.Memory, tiaMem chipbus.Memory) *Ports
  • func (p *Ports) AttachPlugMonitor(m plugging.PlugMonitor)
  • func (p *Ports) DisablePeripherals(disabled bool)
  • func (p *Ports) End()
  • func (p *Ports) HandleInputEvent(inp InputEvent) (bool, error)
  • func (p *Ports) MutePeripherals(muted bool)
  • func (p *Ports) PeekField(fld string) interface{}
  • func (p *Ports) PeripheralID(id plugging.PortID) plugging.PeripheralID
  • func (p *Ports) Plug(port plugging.PortID, c NewPeripheral) error
  • func (p *Ports) Plumb(riotMem chipbus.Memory, tiaMem chipbus.Memory)
  • func (p *Ports) PokeField(fld string, v interface{})
  • func (p *Ports) ResetPeripherals()
  • func (p *Ports) RestartPeripherals()
  • func (p *Ports) Snapshot() *Ports
  • func (p *Ports) Step()
  • func (p *Ports) String() string
  • func (p *Ports) Update(data chipbus.ChangedRegister) bool
  • func (p *Ports) WriteINPTx(inptx chipbus.Register, data uint8)
  • func (p *Ports) WriteSWCHx(id plugging.PortID, data uint8)
• type RestartPeripheral
• type TimedInputEvent

Constants

const (
	PowerOff = "emulated machine has been powered off"
)

Sentinal error returned when PanelPowerOff event is received.

Types

type DisablePeripheral

type DisablePeripheral interface {
	Disable(bool)
}

DisablePeripheral is implemented by peripherals that can be disabled. This is useful for peripherals that do not act well during rewinding.

type Event

type Event string

Event represents the actions that can be performed at one of the VCS ports, either the panel or one of the two player ports.

const (
	NoEvent Event = "NoEvent" // nil

	// fire will be interpreted by both stick and paddle depending on which
	// controller is attached.
	Fire Event = "Fire" // bool

	// joystick.
	Centre    Event = "Centre"    // nil
	Up        Event = "Up"        // EventDataStick
	Down      Event = "Down"      // EventDataStick
	Left      Event = "Left"      // EventDataStick
	Right     Event = "Right"     // EventDataStick
	LeftUp    Event = "LeftUp"    // EventDataStick
	LeftDown  Event = "LeftDown"  // EventDataStick
	RightUp   Event = "RightUp"   // EventDataStick
	RightDown Event = "RightDown" // EventDataStick

	// gamepad second button
	SecondFire Event = "SecondFire" // bool

	// paddles.
	PaddleSet Event = "PaddleSet" // float32

	// keyboard.
	KeypadDown Event = "KeypadDown" // rune
	KeypadUp   Event = "KeypadUp"   // nil

	// panel.
	PanelSelect Event = "PanelSelect" // bool
	PanelReset  Event = "PanelReset"  // bool

	PanelSetColor      Event = "PanelSetColor"      // bool
	PanelSetPlayer0Pro Event = "PanelSetPlayer0Pro" // bool
	PanelSetPlayer1Pro Event = "PanelSetPlayer1Pro" // bool

	PanelToggleColor      Event = "PanelToggleColor"      // nil
	PanelTogglePlayer0Pro Event = "PanelTogglePlayer0Pro" // nil
	PanelTogglePlayer1Pro Event = "PanelTogglePlayer1Pro" // nil

	PanelPowerOff Event = "PanelPowerOff" // nil
)

List of defined events. The comment indicates the expected type of the associated EventData. In all cases the EventData can also be EventDataPlayback, indicating that the event has been read from a playback file and will need further parsing.

type EventData

type EventData interface{}

EventData is the value associated with the event. The underlying type should be restricted to bool, float32, or int. string is also acceptable but for simplicity of playback parsers, the strings "true" or "false" should not be used and numbers should be represented by float32 or int never as a string.

type EventDataPlayback

type EventDataPlayback string

EventData is from playback file and will need further parsing.

type EventDataStick

type EventDataStick string

Event data for stick types.

const (
	DataStickTrue  EventDataStick = "true"
	DataStickFalse EventDataStick = "false"
	DataStickSet   EventDataStick = "set"
)

List of valid values for EventDataStick.

A note on the values. DataStickTrue will set the bits associated with the Event and DataStickFalse will unset the bits. DataStickSet will set the bits AND unset any bits not associated the events.

When you use DataStickSet and when you use DataStickTrue/DataStickFalse depends on the harware controller being used to create the input. For DPad devices the DataStickSet should be used; for keyboard devices then the true/false forms are preferred.

NB: true and false are used to maintain compatibility with earlier version of the playback fileformat.

type InputEvent

type InputEvent struct {
	Port plugging.PortID
	Ev   Event
	D    EventData
}

InputEvent defines the data required for single input event.

type NewPeripheral

type NewPeripheral func(*instance.Instance, plugging.PortID, PeripheralBus) Peripheral

NewPeripheral defines the function signature for a creating a new peripheral, suitable for use with AttachPloyer0() and AttachPlayer1().

type Peripheral

type Peripheral interface {
	// String should return information about the state of the peripheral
	String() string

	// Periperhal is to be removed
	Unplug()

	// Snapshot the instance of the Peripheral
	Snapshot() Peripheral

	// Plumb a new PeripheralBus into the Peripheral
	Plumb(PeripheralBus)

	// The port the peripheral is plugged into
	PortID() plugging.PortID

	// The ID of the peripheral being represented
	ID() plugging.PeripheralID

	// handle an incoming input event
	HandleEvent(Event, EventData) (bool, error)

	// memory has been updated. peripherals are notified.
	Update(chipbus.ChangedRegister) bool

	// step is called every CPU clock. important for paddle devices
	Step()

	// reset state of peripheral. this has nothing to do with the reset switch
	// on the VCS panel
	Reset()

	// whether the peripheral is currently "active"
	IsActive() bool
}

Peripheral represents a (input or output) device that can plugged into the ports of the VCS.

type PeripheralBus

type PeripheralBus interface {
	WriteINPTx(inptx chipbus.Register, data uint8)

	// the SWCHA register is logically divided into two nibbles. player 0
	// uses the upper nibble and player 1 uses the lower nibble. peripherals
	// attached to either player port *must* only use the upper nibble. this
	// write function will transparently shift the data into the lower nibble
	// for peripherals attached to the player 1 port.
	//
	// also note that peripherals do not need to worry about preserving bits
	// in the opposite nibble. the WriteSWCHx implementation will do that
	// transparently according to which port the peripheral is attached
	//
	// Peripherals attached to the panel port can use the entire byte of the
	// SWCHB register
	WriteSWCHx(id plugging.PortID, data uint8)
}

PeripheralBus defines the memory operations required by peripherals. We keep this bus definition here rather than the Bus package because it is very specific to this package and sub-packages.

type Ports

type Ports struct {
	Panel       Peripheral
	LeftPlayer  Peripheral
	RightPlayer Peripheral
	// contains filtered or unexported fields
}

Input implements the input/output part of the RIOT (the IO in RIOT).

func NewPorts

func NewPorts(instance *instance.Instance, riotMem chipbus.Memory, tiaMem chipbus.Memory) *Ports

NewPorts is the preferred method of initialisation of the Ports type.

func (*Ports) AttachPlugMonitor

func (p *Ports) AttachPlugMonitor(m plugging.PlugMonitor)

AttchPlugMonitor implements the plugging.Monitorable interface.

func (*Ports) DisablePeripherals

func (p *Ports) DisablePeripherals(disabled bool)

DisabledPeripherals calls restart on any attached peripherals that implement that DisablePeripheral interface.

func (*Ports) End

func (p *Ports) End()

func (*Ports) HandleInputEvent

func (p *Ports) HandleInputEvent(inp InputEvent) (bool, error)

HandleInputEvent forwards the InputEvent to the perupheral in the correct port. Returns true if the event was handled and false if not.

func (*Ports) MutePeripherals

func (p *Ports) MutePeripherals(muted bool)

MutePeripherals sets the mute state of peripherals that implement the mutePeripheral interface.

func (*Ports) PeekField

func (p *Ports) PeekField(fld string) interface{}

PeekField returns the value of the named field.

This is the same as a Peek() on the equivalent memory location in most cases, but there are a couple of fields that are not directly associated with a memory location.

swacnt, swcha, swacnt and swbcnt are directly as they would be if read by Peek()

swcha_w and swchb_w are the swcha and swchb values as most recently written by the 6507 program (or with the PokeField() function)

swcha_derived is the value SWCHA should be if the RIOT ports logic hasn't been interfered with. swcha_derived and swcha may be unequal because of a Poke() or PokeField("swcha").

swchb_derived is the same as swcha_derived except for SWCHB register.

func (*Ports) PeripheralID

func (p *Ports) PeripheralID(id plugging.PortID) plugging.PeripheralID

PeripheralID returns the ID of the peripheral in the identified port.

func (*Ports) Plug

func (p *Ports) Plug(port plugging.PortID, c NewPeripheral) error

Plug connects a peripheral to a player port.

func (*Ports) Plumb

func (p *Ports) Plumb(riotMem chipbus.Memory, tiaMem chipbus.Memory)

Plumb new ChipBusses into the Ports sub-system. Depending on context it might be advisable for ResetPeripherals() to be called after plumbing has succeeded.

func (*Ports) PokeField

func (p *Ports) PokeField(fld string, v interface{})

PokeField sets the named field with a new value.

Fieldnames the same as described for PeekField() except that you cannot update the swchb_derived field.

func (*Ports) ResetPeripherals

func (p *Ports) ResetPeripherals()

ResetPeripherals to an initial state.

func (*Ports) RestartPeripherals

func (p *Ports) RestartPeripherals()

RestartPeripherals calls restart on any attached peripherals that implement that the RestartPeripheral interface.

func (*Ports) Snapshot

func (p *Ports) Snapshot() *Ports

Snapshot returns a copy of the RIOT Ports sub-system in its current state.

func (*Ports) Step

func (p *Ports) Step()

Step input state forward one cycle.

func (*Ports) String

func (p *Ports) String() string

func (*Ports) Update

func (p *Ports) Update(data chipbus.ChangedRegister) bool

Update checks to see if ChipData applies to the Input type and updates the internal controller/panel states accordingly. Returns true if ChipData requires more attention.

func (*Ports) WriteINPTx

func (p *Ports) WriteINPTx(inptx chipbus.Register, data uint8)

WriteINPTx implements the peripheral.PeripheralBus interface.

func (*Ports) WriteSWCHx

func (p *Ports) WriteSWCHx(id plugging.PortID, data uint8)

WriteSWCHx implements the peripheral.PeripheralBus interface.

type RestartPeripheral

type RestartPeripheral interface {
	Restart()
}

RestartPeripheral is implemented by peripherals that can significantly change configuration. For example, the AtariVox can make use of an external program which might be changed during the emulation.

Restarting is a special event and should not be called too often due to the possible nature of configuration changes.

type TimedInputEvent

type TimedInputEvent struct {
	Time coords.TelevisionCoords
	InputEvent
}

TimedInputEvent embeds the InputEvent type and adds a Time field (time measured by TelevisionCoords).