[COMMITTED] MI foundations

[Jose E. Marchesi]

Hi kostasch, and people!

I just pushed a fat commit that adds the foundations for the
Machine-Interface support.  Basically the boring stuff ;)

A minimal MI is now in place, on which you can build/improve/complete.
Please take a look.

Some notes:

MI overview
===========

A `client application' can communicate with poke through the
machine-interface:

+--------+       MI     +--------+
| client |------ O------|  poke  |
+--------+              +--------+

There are two ways in which the communication can be performed:
through pipes and through TCP network connections.

When using the pipe operation mode, the client application runs poke
as a sub process.  Data is obtained from poke reading from its
standard output, and data is fed to poke writing to its standard
input:

+--------+        stdin +--------+
| client |------------->|  poke  |
+--------+              +--------+
    ^                       | stdout
    |                       |
    +-----------------------+

When using the TCP network operation mode the client uses a
bidirectional socket to communicate with a running poke process.  This
has the advantage of allowing having poke and the client application
running on different machines:

+--------+ socket    (----)__     socket +--------+
| client |<-------->( network )<-------->|  poke  |
+--------+           (-------)           +--------+

If not using network sockets, poke starts talking MI immediately using
the standard input and standard output:

$ poke --mi
^@^@^@G{"poke_mi":0,"type":2,"data":{"type":0,"args":{"version":"0.1-beta"}}}

Running poke in MI mode
=======================

When using sockets, poke prints the number of the socket where it is
listening for requests in the standard output:

$ poke --mi --mi-socket=0
1234

Further communication is performed in the socket.

Transport Protocol
==================

At the lowest level the communication is performed in terms of "frame
messages".

The layout of each message is:

    deftype PMI_FrameMessage =
    struct
    {
      big uint<4> size : size <= 2048;
      byte[size] payload;
    }

Where `size' is the length of the payload, measured in bytes.  The
maximum ength of a frame message payload is two kilobytes.

The file pk-mi.c implements this protocol and offers functions to both
receive and send frame messages.

MI Protocol
===========

MI messages can be one of:

`Requests' are initiated by the client.  Once a request is sent, it will
trigger a response.  The response is paired with the triggering request
by the request's sequence number.

`Responses' are initiated by poke, in response to a request received
from the client.

`Events' are initiated by poke.

The MI protocol message data structures are implemented in
poke/pk-mi-msg.[ch].

MI messages are encoded in JSON and put in the payload in a frame
message for transmission.  The JSON support in poke is in
poke/pk-mi-json.[ch].

IMPORTANT: please keep the usage of the json-c library confined in
pk-mi-json.[ch].

At the moment the following messages are implemented:

- Event INITIALIZED

  Poke sends this event to the client application when it has finished
  initializing.

- Request EXIT

  Ask poke to exit.

- Response EXIT

  Reply to an EXIT request.

PoK: a prototype GUI
====================

The directory PoK contains a testing/proof-of-concept GUI for poke, that
uses the MI interface.  PoK is an acronym for "Proof of Koncept" :)

The main purpose of PoK is twofold:
- To explore the best way for a graphical tool to interact with poke.
- To make sure poke's machine interface (MI) is complete and effective.

PoK is written in Tcl/Tk.  To run it, you need:
- Recent versions of Tcl and Tk installed in your system.
- The bwidget package installed in your system.  It is available in both
  Debian-based and RPM-based distros.

Running PoK:

$ cd PoK
$ ./pok

Note that PoK will use the `poke' program in the path.  This probably
means an installed poke.  If you want to run the uninstalled poke, do
something like this instead:

$ cd PoK
$ ../build/run ./pok

Even if it doesn't do much yet, it is already communicating with poke
thru the machine-interface.

When you run PoK, you will see that the poke version is shown in the
indication area at the bottom-right of the main window.  The version is
part of the payload of the event "initialized":
    
       PoK <-- EVENT_INITIALIZED -- poke

When you use the File-Exit menu to exit PoK, the following MI
interchange happens:

       PoK  -- REQUEST_EXIT --> poke
       PoK <-- RESPONSE_EXIT -- poke

You can use the --debug-mi in order to get debug traces on the MI
messages exchanged between PoK and poke:

$ ./pok --debug-mi
MI: recv: poke_mi 0 type 2 data {type 0 args {version 0.1-beta}}
MI: sent: poke_mi 0 type 0 data {type 0}
MI: recv: poke_mi 0 type 1 data {type 0 success_p true req_number 1}

I will be updating the GUI's capabilities as the MI becomes more and
more capable.  It will also serve as a sandbox where to establish
requirements for the MI.

Documentation
=============

The MI is documented in the poke manual.  The proper place is "The
Machine-Interface" chapter.

The documentation should cover:
- Usage instructions.
- A complete description of the MI protocol.
- Hints on how to integrate a client application.