SCRYDOSBox-XReferenceHardwareport

DOSBox-XHardware

port

Read or write one I/O port, and be told when no device answers there.

port(method, port=null, bits=8, value=null)

Try it

On Bricks, the game this repository builds, stopped on its play screen.
Ask

Read VGA port 3C8h, the index of the next palette entry to be written.

Call
port(method="read", port="0x3C8")
Reply 4 of 5 fields
{
  "summary": "port read: 8-bit read of 0x03C8: 0x28",
  "port": "0x03C8",
  "bits": 8,
  "value": "0x28"
}

Port 0x3C8 reads 0x28, an 8-bit value: the next palette entry to be written is 40.

The whole reply
JSON
{
  "summary": "port read: 8-bit read of 0x03C8: 0x28",
  "status": "ok",
  "port": "0x03C8",
  "bits": 8,
  "value": "0x28"
}

The two methods

method what it does
read Reads the port and returns its value. Takes port and bits.
write Sends value to the port. Takes port, value and bits.

Arguments

method one of "read", "write", required
read or write, as above.
port integer or string, optional
The port: an integer or 0x hex, 0 to 0xFFFF.
bits one of 8, 16, 32, default 8
The size of the access: 8, 16 or 32 bits. Left out, 8.
value integer or string, optional
What a write sends: an integer or 0x hex, no wider than bits.

What comes back

value
What the read returned, or what the write sent, as 0x text at the width of bits.
port
The port, as four hex digits.
readback
On a write: always unavailable, available: false with its why, because a port holds no value to read back.
All 4 reply fields
  • bits (integer)
  • port (string)
  • readback (object)
  • value (string)

What it refuses

Why it works this way

The debugger's PORTINFO is asked before every access, because a port with no device reads all ones and takes a write in silence: nothing in the value says so.

It reports each width apart, and an access the emulator splits byte by byte reaches a device only if every byte does. So a 16-bit read of 0x3DA is refused where an 8-bit one answers.

A read marks the session altered too: reading a port is a bus cycle the device sees.

The contract your client receives
Text
One access of an I/O port, the one kind a memory write cannot make. Marks the session
`altered`, a read too: reading a port can change its device (3DAh resets the attribute
flip-flop, 60h takes the key). Needs the machine stopped and a build whose debugger has
`PORTINFO`. `port` and `value` are integers or `0x` hex, as the reply spells them.

`read`: `port`, `bits` (8, 16 or 32). Reply: `port`, `bits`, `value`.

`write`: `port`, `value`, `bits`. Reply: `port`, `bits`, `value`, `readback` (unavailable:
a port holds no value to read back).

Refused (`bad_argument`): a port past 0xFFFF, a value wider than `bits`, an argument the
method does not take. `no_channel`: a port no device answers at that size and side (the
emulator would answer all ones, or swallow the write, in silence), or no `PORTINFO`.
`not_stopped`: a running guest. `unexpected_answer`: the debugger answered another shape.

Reference: REFERENCE.md, The machine's hardware.
Tools