SCRYDOSBox-XReferenceHardwareport
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
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 readorwrite, as above.- port integer or string, optional
- The port: an integer or
0xhex, 0 to0xFFFF. - bits one of
8,16,32, default8 - The size of the access: 8, 16 or 32 bits. Left out, 8.
- value integer or string, optional
- What a
writesends: an integer or0xhex, no wider thanbits.
What comes back
- value
- What the read returned, or what the write sent, as
0xtext at the width ofbits. - port
- The port, as four hex digits.
- readback
- On a
write: always unavailable,available: falsewith itswhy, because a port holds no value to read back.
All 4 reply fields
bits(integer)port(string)readback(object)value(string)
What it refuses
- A machine that is running (
not_stopped). - A port past
0xFFFF, a value wider thanbits, or an argument the method does not take (bad_argument). - A port no device answers at that size and direction (
no_channel). - A DOSBox-X whose debugger has no
PORTINFOcommand (no_channel). - A debugger answer in a shape the tool does not know (
unexpected_answer).
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.
Related tools
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.