REFERENCE SECTION on SYNTAX and SEMANTICS of MESSAGES
Message Format
A message has the following parts:
| Size | Name | Description
| | 4 Byte | Header | (TYPE,SIZE,SLOT,ID) |
| 4 Byte | Timestamp | (optional) |
| 8 Byte | Address | (optional) |
| 1-256 Octabyte | Payload | (optional) |
The header together with the optional timestamp and the optional address
is called the extended header.
Message TYPE
The TYPE Byte in the Header has the following bits:
bus, time, address, route, payload, request, lock, unused
These bit have the following semantics:
bus bit 1
This is a message for/from the bus (motherboard).
The bus will handle this message.
The type of the message is determined by the ID byte (see below).
bus bit 0
This is a message from device to device which just needs to be
forwarded by the bus.
time bit 1
the four byte header is followed by a four byte time stamp
that may be incremented by the bus and other components to provide
timing information.
time bit 0
there is no time time stamp after the header
address bit 1
the four byte header and the optional four byte time stamp
are followed by an eight byte address.
if the route bit is not set, ignore SLOT and determine
the receiver from the address
address bit 0
there is no 8 byte address after the header.
route bit 1
if this bit is set, send the message to the SLOT byte.
route bit 0
if the address bit is set, determine the receiver from the address,
otherwise there is no receiver, which may be OK for bus messages,
or if the ID is 0 (ignore)
payload bit 1
if the payload bit is set, the extended header is followed by a payload.
Its size as a multiple of octas is given by the SIZE byte as SIZE+1.
This allows from 1 octa up to 256 octas payload = 2k byte.
For an empty payload just don't set the payload bit.
payload bit 0
there is no payload after the extended header.
request bit 1
if this bit is set, the bus will set the SLOT byte to the sender slot
before delivering the message but after determining
the receiver (which might be specified by the SLOT). This allows
the receiver to send an answer using the route bit.
If the request bit is set, the sending device will expect an answer.
If there is no receiving device or if the receiving device disconnects
before sending an answer, the bus should provide a dummy answer.
request bit 0
The SLOT byte is not changed, there will be no answer expected.
lock bit 1
if this bit is set, the bus is locked for exclusive access according to
the following rules:
After the bus accepts a message with the lock bit, no other message will
be accepted or delivered until the bus gets unlocked again.
The the bus then repeats the following two steps:
1. It will deliver the message to the receiver.
2. Then it will wait until the receiver sends a message.
The bus is unlocked as soon as a message without the lock bit has been
delivered (after step 1 above).
To unlock the bus the final receiver can send a message with four
zero byte (without address and route bit, and id=0, it will be ignored).
Message Size
The message size can be determined from the first two byte
(the TYPE and the SIZE byte of the header) of the message.
It is computed as follows:
The minimum size of the message is 4 byte.
(the message consists of just the header)
Add 4, if the time bit in the TYPE byte is set.
Add 8, if the address bit in the TYPE byte is set.
Add 8*(SIZE+1), if the payload bit in the TYPE byte is set.
Summary of the predefined Message ID's
#define ID_IGNORE 0
Message Format: 4 to 16 Byte
| TYPE | (bus=0, time=any, address=any, route=any,
payload=0, request=0, lock=any, unused=any)
|
| SIZE | any
|
| SLOT | any
|
| ID | 0
|
if time bit set
|
| time | any (4 Byte)
|
if address bit set
|
| address | any (8 Byte)
|
Semantics:
The sender of such a message can use the route bit and the SLOT,
or the address bit and the address field to determine the receiver.
If neither is specified the bus will ignore this message (but may
unlock).
The receiver can safely ignore this message.
#define ID_READ 1
Message Format: 12 to 16 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=0, request=1, lock=any, unused=any)
|
| SIZE | any
|
| SLOT | any
|
| ID | 1
|
if time bit set
|
| time | any (4 Byte)
|
| address | any (8 Byte)
|
Semantics:
The sender of this message will expect a answer containing
(SIZE+1)*8 byte at the given address.
The answer should have ID = ID_READREPLY
(or ID=ID_NOREPLY in case of an error).
The bus will replace the SLOT byte by the sending slot number, such
that the receiver of the message can send an answer using the route bit.
The bus will make sure that eventually the sender will receive an answer.
The receiver should send a answer with ID=ID_READREPLY to the device
given in the SLOT byte using the route bit. It should add SIZE+1 octas
of payload containing the memory content starting at the given address.
#define ID_WRITE 2
Message Format: 20 to 16+256*8 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=1, request=0, lock=any, unused=any)
|
| SIZE | any
|
| SLOT | any
|
| ID | 2
|
| if time bit set
|
| time | any (4 Byte)
|
| address | any (8 Byte)
|
| payload | any ((SIZE+1)*8 Byte)
|
Semantics:
The sender of this message will expect that the SIZE+1 octas contained
in the payload will be stored by the receiver at the given address.
The receiver will store the data. There is no answer.
#define ID_READREPLY 3
Message Format: 20 to 16+256*8 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=1, request=0, lock=any, unused=any)
|
| SIZE | any
|
| SLOT | any
|
| ID | 3
|
| if time bit set
|
| time | any (4 Byte)
|
| address | any (8 Byte)
|
| payload | any ((SIZE+1)*8 Byte)
|
Semantics:
The sender of this message will inform the receiver
that the SIZE+1 octas contained in the payload
are stored at the given address.
The receiver can use the data.
#define ID_NOREPLY 4
Message Format: 12 to 16 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=0, request=0, lock=any, unused=any)
|
| SIZE | any
|
| SLOT | any
|
| ID | 4
|
| if time bit set
|
| time | any (4 Byte)
|
| address | any (8 Byte)
|
Semantics:
The sender of this message will inform the receiver
that the read request just received can not be answered.
The sender may be either a device or the bus.
Typically the sender of such a message should also raise
an interrupt to cause proper error treatment.
The receiver should treat this message as a (soft) read error.
It can also ignore this message and process the interrupt
caused by an unsuccessful read.
#define ID_READBYTE 5
#define ID_READWYDE 6
#define ID_READTETRA 7
Message Format: 12 to 16 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=0, request=1, lock=any, unused=any)
|
| SIZE | any
|
| SLOT | any
|
| ID | 5,6, or 7
|
| if time bit set
|
| time | any (4 Byte)
|
| address | any (8 Byte)
|
Semantics:
The sender of this message will expect a answer containing
1 (READBYTE), 1 (READWYDE) or 4 (READTETRA) byte at the given address.
The answer should have IDID_BYTEREPLY, ID=ID_WYDEREPLY, or
ID=ID_TETRAREPLY
(or ID=ID_NOREPLY in case of an error).
The bus will replace the SLOT byte by the sending slot number, such
that the receiver of the message can send an answer using the route bit.
The bus will make sure that eventually the sender will receive an answer.
The receiver should send a answer with ID=ID_BYTEREPLY, ID=ID_WYDEREPLY, or
ID=ID_TETRAREPLY to the device given in the SLOT byte using the route bit.
It should add 1 octa of payload containing left justified the
memory content (1, 2, or 4 byte) starting at the given address.
#define ID_WRITEBYTE 8
#define ID_WRITEWYDE 9
#define ID_WRITETETRA 10
Message Format: 20 to 24 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=1, request=0, lock=any, unused=any)
| | SIZE | 0
| | SLOT | any
| | ID | 8, 9, or 10
| | if time bit set
| | time | any (4 Byte)
| | address | any (8 Byte)
| | payload | any (8 Byte
|
Semantics:
The sender of this message will expect that 1, 2 or 4 byte contained
left justified in the payload will be stored by the receiver
at the given address.
The receiver will store the data. There is no answer.
#define ID_BYTEREPLY 11
#define ID_WYDEREPLY 12
#define ID_TETRAREPLY 13
Message Format: 20 to 24 Byte
| TYPE | (bus=0, time=any, address=1, route=any,
payload=1, request=0, lock=any, unused=any)
| | SIZE | 0
| | SLOT | any
| | ID | 11, 12, or 13
| | if time bit set
| | time | any (4 Byte)
| | address | any (8 Byte)
| | payload | any (8 Byte)
|
Semantics:
The sender of this message will inform the receiver
that the 1, 2, or 4 byte contained left justified in the payload octa
are stored at the given address.
The receiver can use the data.
#define ID_TERMINATE 0xF9
Message Format: 4 Byte
| TYPE | (bus=1, time=0, address=0, route=0,
payload=0, request=0, lock=0, unused=0)
| | SIZE | 0
| | SLOT | 0
| | ID | 0xF9
|
Semantics:
Sending this message is a polite request to terminate the device
simulator. The motherboard will send this message to all connected
devices before it terminates. This allows to terminate the complete
device configuration by terminating the motherboard.
Of course it is possible to ignore this message. For example, the VMB IDE
application will not terminate when receiving this message.
#define ID_REGISTER 0xFA
Message Format: 36 to 12+8*256 Byte
| TYPE | (bus=1, time=any, address=0, route=0,
payload=1, request=0, lock=any, unused=any)
| | SIZE | any
| | SLOT | any
| | ID | 0xFA
| | if time bit set
| | time | any (4 Byte)
| | payload | any (8 Byte)
|
Semantics:
The sender of this message tries to register itself with the bus.
The payload will contain in this order:
- the address (8 byte)
- the limit (8 byte)
- the interrupt mask (8byte)
- the name (a multiple of 8 byte)
- optional: the version number (4 byte major, 4 byte minor)
- optional: further information yet unspecified.
The SIZE byte should correctly specify the amount of payload supplied
which varies because of the name.
The registered device claims to be responsible for the memory
range starting at the given address up to but not including the limit.
Any interrupt, where interrupt numbers range between 0 and 63,
that is raised will be delivered to this device if the corresponding
bit in the interrupt mask is set.
The name that follows in the payload is a zero terminated string
left justified in the payload. The payload may be longer than the string
because the payload is always a multiple of 8 byte. The name of the
device is just for information.
The next 8 byte, if they exist, contain the version number of the device.
Currently, a device can register only once. It is planed to change this so
that a device can register and unregister for multiple memory ranges, possibly
occupying multiple slots, but using only a single TCP/IP connection.
#define ID_UNREGISTER 0xFB
Message Format: 4 to 8 Byte
| TYPE | (bus=1, time=any, address=0, route=0,
payload=0, request=0, lock=any, unused=any)
| | SIZE | any
| | SLOT | any
| | ID | 0xFB
| | if time bit set
| | time | any (4 Byte)
|
Semantics:
A registered device should unregister itself before disconnecting.
#define ID_INTERRUPT 0xFC
Message Format: 4 to 8 Byte
| TYPE | (bus=1, time=any, address=0, route=0,
payload=0, request=0, lock=0, unused=any)
| | SIZE | any
| | SLOT | 0 to 63
| | ID | 0xFC
| | if time bit set
| | time | any (4 Byte)
|
Semantics:
The sender of this message raises an interrupt. The interrupt number
should be a number between 0 and 63 nd is contained in the SLOT byte.
The bus will check all registered devices and if the corresponding bit
in the interrupt mask is set, it will forward this message to the device.
The receiver of this message should take note of the interrupt and
process it.
#define ID_RESET 0xFD
Message Format: 4 to 8 Byte
| TYPE | (bus=1, time=any, address=0, route=0,
payload=0, request=0, lock=0, unused=any)
| | SIZE | any
| | SLOT | any
| | ID | 0xFD
| | if time bit set
| | time | any (4 Byte)
|
Semantics:
This is the hardware reset signal. This is not a software interrupt.
Even if the software of a device is spinning in a loop or got stuck
otherwise the receiver should be able to process this message and get
back into a sane initial state.
Devices typically do not send this signal. It is send out by the
motherboard/bus.
#define ID_POWEROFF 0xFE
Message Format: 4 to 8 Byte
| TYPE | (bus=1, time=any, address=0, route=0,
payload=0, request=0, lock=0, unused=any)
| | SIZE | any
| | SLOT | any
| | ID | 0xFE
| | if time bit set
| | time | any (4 Byte)
|
Semantics:
This is not a power fail interrupt, or something that a device can handle;
its definitely the end of power. If the device has no (virtual) battery
it should stop operating. The power off signal will only come after
a power on signal.
#define ID_POWERON 0xFF
Message Format: 4 to 8 Byte
| TYPE | (bus=1, time=any, address=0, route=0,
payload=0, request=0, lock=0, unused=any)
| | SIZE | any
| | SLOT | any
| | ID | 0xFF
| | if time bit set
| | time | any (4 Byte)
|
Semantics:
This is signal is the beginning of life for a device.
The device should wait after registering until it receives
the power on signal. Then it should start working.
|