ports

Documentation

Overview

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

Emulated peripherals are plugged into the VCS with the Plug() function. Input from "real" devices is handled by HandleEvent() which passes the event to peripherals in the specified PortID.

Peripherals write back to the VCS through the PeripheralBus.

Index

• Constants
• type Event
• type EventData
• type EventDataPlayback
• type EventDataStick
• type EventPlayback
• type EventRecorder
• type NewPeripheral
• type Peripheral
• type PeripheralBus
• type Ports
  • func NewPorts(riotMem bus.ChipBus, tiaMem bus.ChipBus) *Ports
  • func (p *Ports) AttachEventRecorder(r EventRecorder)
  • func (p *Ports) AttachPlayback(b EventPlayback)
  • func (p *Ports) AttachPlugMonitor(m plugging.PlugMonitor)
  • func (p *Ports) GetPlayback() error
  • func (p *Ports) HandleEvent(id plugging.PortID, ev Event, d EventData) error
  • func (p *Ports) Plug(port plugging.PortID, c NewPeripheral) error
  • func (p *Ports) Plumb(riotMem bus.ChipBus, tiaMem bus.ChipBus)
  • func (p *Ports) Reset()
  • func (p *Ports) Snapshot() *Ports
  • func (p *Ports) Step()
  • func (p *Ports) String() string
  • func (p *Ports) Update(data bus.ChipData) bool
  • func (p *Ports) WriteINPTx(inptx addresses.ChipRegister, data uint8)
  • func (p *Ports) WriteSWCHx(id plugging.PortID, data uint8)

Constants

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

Sentinal error returned when PanelPowerOff event is received.

Types

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

	// paddles.
	PaddleSet Event = "PaddleSet" // float64

	// keyboard.
	KeyboardDown Event = "KeyboardDown" // rune
	KeyboardUp   Event = "KeyboardUp"   // 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 EventPlayback

type EventPlayback interface {
	// note the type restrictions on EventData in the type definition's
	// commentary
	GetPlayback() (plugging.PortID, Event, EventData, error)
}

Playback implementations feed controller Events to the device on request with the CheckInput() function.

Intended for playback of controller events previously recorded to a file on disk but usable for many purposes I suspect. For example, AI control.

type EventRecorder

type EventRecorder interface {
	RecordEvent(plugging.PortID, Event, EventData) error
}

EventRecorder implementations mirror an incoming event.

Implementations should be able to handle being attached to more than one peripheral at once. The ID parameter of the EventRecord() function will help to differentiate between multiple devices.

type NewPeripheral

type NewPeripheral func(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

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

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

	// Name should return the canonical name for the peripheral (eg. "Paddle"
	// for the paddle peripheral). It shouldn't include information about which
	// port the peripheral is attached to.
	Name() string

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

	// memory has been updated. peripherals are notified.
	Update(bus.ChipData) 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()
}

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

type PeripheralBus

type PeripheralBus interface {
	WriteINPTx(inptx addresses.ChipRegister, 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(riotMem bus.ChipBus, tiaMem bus.ChipBus) *Ports

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

func (*Ports) AttachEventRecorder

func (p *Ports) AttachEventRecorder(r EventRecorder)

AttachEventRecorder attaches an EventRecorder implementation to all ports that implement RecordablePort.

func (*Ports) AttachPlayback

func (p *Ports) AttachPlayback(b EventPlayback)

AttachPlayback attaches an EventPlayback implementation to all ports that implement RecordablePort.

func (*Ports) AttachPlugMonitor

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

AttchPlugMonitor implements the plugging.Monitorable interface.

func (*Ports) GetPlayback

func (p *Ports) GetPlayback() error

GetPlayback requests playback events from all attached and eligible peripherals.

func (*Ports) HandleEvent

func (p *Ports) HandleEvent(id plugging.PortID, ev Event, d EventData) error

HandleEvent forwards the Event and EventData to the device connected to the specified PortID.

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 bus.ChipBus, tiaMem bus.ChipBus)

Plumb new ChipBusses into the Ports sub-system.

func (*Ports) Reset

func (p *Ports) Reset()

Reset peripherals to an initial state.

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 bus.ChipData) 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 addresses.ChipRegister, data uint8)

WriteINPTx implements the MemoryAccess interface.

func (*Ports) WriteSWCHx

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

WriteSWCHx implements the MemoryAccess interface.