X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=hostinfod%2Fhostinfo-protocol.pod;h=f322bca3b8368598fb617bc67a2d87190fb8e770;hb=093d4be606a60459dea1c9a62616429596957385;hp=df838c037e4b20e3a789db79f6a871879ddbb720;hpb=dcbfcc566fa812fd3085c89a8cfed7fe34bb05e8;p=virt-hostinfo.git diff --git a/hostinfod/hostinfo-protocol.pod b/hostinfod/hostinfo-protocol.pod index df838c0..f322bca 100644 --- a/hostinfod/hostinfo-protocol.pod +++ b/hostinfod/hostinfo-protocol.pod @@ -6,8 +6,8 @@ hostinfo-protocol - hostinfo client commands and protocol =head1 SYNOPSIS - >>> PING "hello" - <<< 1.0 200 hello + <<< PING "hello" + >>> 1.0 200 hello =head1 DESCRIPTION @@ -60,15 +60,15 @@ request), and then reading the reply. A typical request/reply cycle looks like: - >>> PING "hello" - <<< 1.0 200 hello + <<< PING "hello" + >>> 1.0 200 hello In this case the request was the literal string C<"PING \"hello\"\r\n"> (note: followed by carriage return [CR] and line feed [LF]). The reply was C<"1.0 200 hello\r\n">. -The EEE and EEE symbols are not part of +The EEE and EEE symbols are not part of the protocol. They indicate messages sent to the host and received from the host respectively. @@ -101,15 +101,15 @@ Some commands (but not PING) can return a multi-line response. A few commands return a multi-line response: - >>> CAPABILITIES - <<< 1.0 200 - <<< Content-Type: text/xml - <<< Content-Length: 123 - <<< - <<< - <<< - <<< - <<< i686 + <<< CAPABILITIES + >>> 1.0 200 + >>> Content-Type: text/xml + >>> Content-Length: 123 + >>> + >>> + >>> + >>> + >>> i686 (etc.) The multi-line response consists of headers and blank line and a body, @@ -128,8 +128,8 @@ followed by the CR LF immediately. For example C<"1.0 200\r\n">. When a command returns an error, the request / response looks like this: - >>> NOSUCHCOMMAND - <<< 1.0 404 Command not found + <<< NOSUCHCOMMAND + >>> 1.0 404 Command not found As in HTTP, C<4xx> and C<5xx> status codes indicate classes of error. Following the error code is an explanatory string. @@ -155,20 +155,156 @@ are not case sensitive, and you can send them in lowercase or mixed case. The request is always a single line, always consists only of 7 bit -printable ASCII (apart from the final CRLF), and must be less or equal -to 4096 characters in length (that includes the final CRLF). +printable ASCII bytes in the range 32-126 (apart from the final CRLF), +and must be less or equal to 4096 bytes in length (that includes the +final CRLF). Arguments that are strings I be quoted (using double-quotes). Special characters inside the strings are escaped using backslashes. -The rules are precisely the same as for C literal strings, so -for example C<"\t"> is a string containing a single tab character. +The rules are precisely the same as for C literal strings, so for +example C<"\t"> is a string containing a single tab character. -Arguments that are integers appear as integer literals. +Strings may not contain C<\0> characters in the middle, nor can they +be NULL. -Other argument types that are allowed are: booleans (I or -I). +Unless specified otherwise, the charset for strings is I, but +any bytes outside the range 32-126 must be sent as escape sequences, +eg. C<"\xC2\xA3"> would encode the pound (currency) sign. -Note that integers, booleans must never be quoted. +Arguments that are integers appear as integer literals, with optional +minus sign (C<->) before. As with C, use a I<0> to indicate octal and +I<0x> to indicate hexadecimal literals. + +Boolean arguments should be sent as I or I. + +=head2 AVAILCPUS + + AVAILCPUS + +=head3 Returns + +Number of available physical cores in the host. + +=head3 Example + + <<< AVAILCPUS + >>> 1.0 200 4 + +=head3 Description + +Returns the number of physical cores in the host that are available to +the virtualization system (ie. have not been disabled). See also +I which would in almost every case return the same number. + +=head2 CORESPERSOCKET + + CORESPERSOCKET + +=head3 Returns + +Number of cores per socket in the physical host. + +=head3 Example + + <<< CORESPERSOCKET + >>> 1.0 200 2 + +=head3 Description + +Returns the number of physical cores per socket in the host. + +=head2 MEMORY + + MEMORY + +=head3 Returns + +Amount of memory in host, in kilobytes. + +=head3 Example + + <<< MEMORY + >>> 1.0 200 2097022 + +=head3 Description + +Returns the total memory in the host, in kilobytes. + +=head2 MHZ + + MHZ + +=head3 Returns + +Speed of host cores in MHz. + +=head3 Example + + <<< MHZ + >>> 1.0 200 2047 + +=head3 Description + +Returns the clockspeed of host cores in MHz. + +=head2 MODEL + + MODEL + +=head3 Returns + +The host CPU model, a string such as C or C. + +=head3 Example + + <<< MODEL + >>> 1.0 200 x86_64 + +=head3 Description + +Returns the host CPU model. + +=head2 NODES + + NODES + +=head3 Returns + +The number of NUMA nodes in the host. + +=head3 Example + + <<< NODES + >>> 1.0 200 1 + +=head3 Description + +Returns the number of NUMA nodes in the host. If this is 1 +then host memory access is uniform. + +=head2 PHYSCPUS + + PHYSCPUS + +=head3 Returns + +The number of physical cores. + +=head3 Example + + <<< PHYSCPUS + >>> 1.0 200 4 + +=head3 Description + +Returns the number of physical cores available on the host. + +In some (highly unusual) situations, some cores might be +disabled. To get the number of cores available to do work, +use C. + +Note that it is common for the guest not to see all of the +physical CPUs (virtual CPUs E physical CPUs). =head2 PING @@ -184,6 +320,11 @@ alpha-numeric characters ([0-9a-zA-Z]{1,16}). Returns C back to the caller. +=head3 Example + + <<< PING "hello" + >>> 1.0 200 hello + =head3 Description This command is used to test the hostinfo connection. @@ -194,8 +335,8 @@ The possible responses to this are: =item * -The command succeeds and echos back the same C string. -This indicates that everything is working. +The command succeeds and echos back the same C string. This +indicates that the connection through to the host daemon is working. =item * @@ -218,6 +359,43 @@ I in the L manual page. =back +=head2 SOCKETSPERNODE + + SOCKETSPERNODE + +=head3 Returns + +The number of sockets on each node. + +=head3 Example + + <<< SOCKETSPERNODE + >>> 1.0 200 2 + +=head3 Description + +Returns the number CPU sockets in each NUMA node. + +=head2 THREADSPERCORE + + THREADSPERCORE + +=head3 Returns + +The number of hyperthreads per core. + +=head3 Example + + <<< THREADSPERCORE + >>> 1.0 200 1 + +=head3 Description + +If hyperthreading is enabled on the host, this returns +the number of threads on each real core. The numbers +returned by C and C are multiplied +accordingly. +