miSim

misim
Class PortMapper

java.lang.Object
  |
  +--misim.PortMapper

public class PortMapper
extends java.lang.Object

The port mapper class provides a convenient way to map a set of port data to a set of inputs, with a simple mapping string. This allows the user of a plugin to wire the various inputs of a complex device into whichever port pins they wish.

Note that a PortMapper is expensive to create, and not especially fast. Plugin writers should only use it where complex wiring is required, and then re-use PortMappers where at all possible.


Constructor Summary
PortMapper(MachineState machineState, java.lang.String mapping, java.lang.String required)
          Create a new PortMapper.
 
Method Summary
 int getBitmask(int portId)
          Returnt the bitmask of the bits we're interested in for the given port
 int getPortBits(char aBit)
          Return the bitmask for this port bit
 int getPortCount()
          Return the number of ports that are mapped
 int getPortData(java.lang.String bits, int data, int portId)
          Prepare data to write the following bits to a given port.
 Port getPortFor(char aBit)
          Return the name of the port that maps this bit.
 int getPortMask(java.lang.String bits, int portId)
          Prepare a mask to write the following bits to a given port This returns a value with bits set to one where the mapped bits exist on this port.
 java.lang.String getPortName(int index)
          Return the name of the given mapped port
 java.util.Vector getPortNames()
          Return the names of all mapped ports.
 java.util.Vector getPortsFor(java.lang.String bits)
          Return a vector of the ports that the following bits are mapped to
 void prepare(int portId, int data)
          Update the port mapper's view of the port, so that data can be read from it with the read or readBit methods.
 int read(java.lang.String bits)
          Read the data from the port mapper for the given set of characters.
 boolean readBit(char bit)
          Return the bit value for a single mapped character Note that characters that have no mapping defined are read as '0'.
 void writeToPort(Port aPort, java.lang.String bits, int data)
          Write the given data to this port, mapping only the supplied bits.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PortMapper

public PortMapper(MachineState machineState,
                  java.lang.String mapping,
                  java.lang.String required)
           throws MiSimException
Create a new PortMapper. Note that this is an expensive operation. The mapping string defines which bits of which ports are to be mapped. Bits are mapped onto characters, and can then be read individually using that character to identify them, or read as numeric values, by using a string of characters to indentify the bitset.

The mapping parameter is a string of port mappings, each separated by a comma. A port mapping is a port name and a set of characters, separated by a colon. The set of characters correspond to bits on the port. The last character in the set corresponds to bit 0, the next to last corresponds to bit 1 and so on. A character 'x' is ignored.

For example: "Port A:DNxxx, Port B:3210"

This maps Bit 3 of Port A to the character 'N' and Bit 4 of Port A to the character 'D'. Bits 3-0 of Port B are mapped to the characters '3', '2','1' and '0' All other port bits are ignored.

Parameters:
machineState - The machine who's ports we are to map
mapping - The mapping String, as defined above
required - A list of required mapping characters that must be defined
Throws:
MiSimException - If the mapping is not well formed.
Method Detail

getPortCount

public int getPortCount()
Return the number of ports that are mapped
Returns:
The number of mapped ports

getPortName

public java.lang.String getPortName(int index)
Return the name of the given mapped port
Parameters:
index - The index of the mapped port
Returns:
The name of the given port

getPortNames

public java.util.Vector getPortNames()
Return the names of all mapped ports.
Returns:
A Vector of the names of the mapped ports

getPortFor

public Port getPortFor(char aBit)
Return the name of the port that maps this bit.
Parameters:
aBit - A Mapped bit
Returns:
The port that this bit is mapped to, or null

getPortsFor

public java.util.Vector getPortsFor(java.lang.String bits)
Return a vector of the ports that the following bits are mapped to
Parameters:
bits - The bits that are mapped
Returns:
A Vector of the ports these bits are mapped to

getPortBits

public int getPortBits(char aBit)
Return the bitmask for this port bit
Parameters:
aBit - A Mapped bit
Returns:
The bitmask for this bit

getBitmask

public int getBitmask(int portId)
Returnt the bitmask of the bits we're interested in for the given port
Parameters:
portId - The port we're interested in
Returns:
The bitmask of all bits mapped on this port

writeToPort

public void writeToPort(Port aPort,
                        java.lang.String bits,
                        int data)
Write the given data to this port, mapping only the supplied bits.
Parameters:
aPort - The port to be written to
bits - The bits to be written, in order they appear in data (MSB first)
data - The data to be written

getPortMask

public int getPortMask(java.lang.String bits,
                       int portId)
Prepare a mask to write the following bits to a given port This returns a value with bits set to one where the mapped bits exist on this port.
Parameters:
bits - The bits to be mapped.
portId - The port that a mask is to be prepared for
Returns:
The mask indicating used bits on this port

getPortData

public int getPortData(java.lang.String bits,
                       int data,
                       int portId)
Prepare data to write the following bits to a given port. This returns the bits in the supplied data mapped to the relevant bit positions for the mapping supplied.
Parameters:
bits - The bits to be mapped, in order they appear in data (MSB first)
data - The data to be mapped
portId - The Id of the port that we shall be writing to
Returns:
The value to be written to the given port

prepare

public void prepare(int portId,
                    int data)
Update the port mapper's view of the port, so that data can be read from it with the read or readBit methods.
Parameters:
portId - The Id of the port that is being written
data - The data on the port

read

public int read(java.lang.String bits)
Read the data from the port mapper for the given set of characters. The set of characters are mapped back to the port bits defined when the mapper was created, and then concatenated into an integer value. Note that characters that have no mapping defined are read as '0'.
Parameters:
bits - A string of mapped characters
Returns:
The numeric value for this set of mapped port bits.

readBit

public boolean readBit(char bit)
Return the bit value for a single mapped character Note that characters that have no mapping defined are read as '0'.
Parameters:
bit - The mapped character to read
Returns:
The boolean value of that bit. 0 = false, 1 = true

miSim