$Header: /CVSROOT/mon/PROTOCOL,v 1.1 2004/09/13 01:14:43 tino Exp $ Definition of the protocol used to "compress" the monitor information: All information is stored under some well to understand dotted names like "linux.cpu.idle". Along with this name there is a data type, which is either unsigned number or string (currently I did not need floats and negative values). These name and type information is compressed into a token number. Numbers are transmitted as deltas (to a previous value or 0) with an optional length prefix if it does not fit into one byte as follows: 00 to BF 0 to 223: Positive delta, directly transmitted Ex (x=0..7) Positive delta, x+1 byte of (number-0xe0) follow Note on strings: This means: "append data" Ex (x=8..f) Negative delta, x-7 byte of number follow Note on strings: Not allowed (or to be defined) Fx x+1 byte of the unsigned number follow Note on strings: This means: "start from the beginning" F8 12 byte unsigned number (future use) F9 16 byte unsigned number (future use) FA Additional index follows FB Same index follows FC Previous index follows FD Reset indexes to no indexes FE future use FF future use Strings are prefixed by their length as number like above, however if they contain FF 16 times in a row there must be an FE following these 16 FFs, the FE itself is ignored. The stream itself consists of "Token Value" pairs, where Token is a number and value is transmitted as the apropriate type. Token numbers start with 1. They are defined on the fly. In case a new token is needed, they are prefixed with a 0-token which always has the datatype "string" with a minimum length of 4 bytes. The first byte of the string gives the datatype of the new token: u for unsigned s for string Everything else is undefined today. After the 0-token the new token value follows (this is for robustness) and the data value, as usual. Example: At the start of the stream, token 0 is preset, so it looks like 00 delta 0, now token 0 0B 'smon.version' type string, 11 byte name (always delta 5) 01 delta 1, now token 1 05 '0.0.0' append 5 bytes to the token's data Now again, token 0 is needed, but we are now at token 1, so you will see: F0 00 absolute 0 0D 'smon.compiled' type string, 12 byte name (delta 5) 02 delta 2, now token 2 0B 'Sep 12 2004' append 11 bytes to the token's data Now we are at token 2 and so on. Tokens can be indexed. Example: linux.cpu.idle for all CPUs, CPU 1 and 2 can be given as follows: [ ...] FA 0 [ ...] FB 1 [ ...] FD Transaction counts for Devices 3,0 and 8,0 can be given as follows: FA 3 FA 0 FC 8 FB 0 FD Note that the "last value" for the delta is stored in the token, and re-used for all indexes. So the last count present is stored as the last value in the token. So usually it's better to create "indexed tokens": F0 00 create token FD special, switches into indexed mode, indexes are reset now! FA 0 indexes follow ... This defines a new (yet unnumbered) token as a copy of (can be token 0 to define some freshly) with the index (and possibly subindex). Note that this type of token still can have subindexes, you can give them afterwards, like this (sets index 0,1,2 on ): F0 00 FD FA 0 FA 1 FA 2 Note that in this case the indexes in use are 0,1,2! Later you can use this normally: FD FA 4 will be ignored! FA 5 FA 6 This means, that index 0,5,6 are used (the 0 for the first index in the token overwrites the 4). If FF is found 17 times in a row, this sets the stream into invalid state. This will eat away any FFs which follow. Then there must be an FE, else the stream is considered invalid until a correct reset sequence is found (17 times FF followed by FE). This is for resynchronization in really weird cases if the data is sent over a stream. Notes: - Reset sequence 17*FF FE not yet supported. - The UDP datagram mode will be defined in future. -Tino $Log: PROTOCOL,v $ Revision 1.1 2004/09/13 01:14:43 tino first version without network monitoring