docs: Convert VD_interfaces to asciidocmanual

TODO!!!! (ended at  6. Base structure of VD interface.)

Related: https://bugs.freedesktop.org/show_bug.cgi?id=95258

2 files changed, 392 insertions, 1 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index b059430e..bf6bc0fb 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -9,10 +9,12 @@ EXTRA_DIST =					\
 	manual.txt				\
 	spice_style.html			\
 	spice_style.txt				\
+	vd_interfaces.txt			\
+	vd_interfaces.html			\
 	$(NULL)
 
 if BUILD_MANUAL
-docfiles = spice_style.html
+docfiles = spice_style.html vd_interfaces.html
 if BUILD_HTML_MANUAL
 docfiles += manual.html
 endif
@@ -34,3 +36,4 @@ clean-local:
 	rm -f manual.html
 	rm -rf manual.chunked
 	rm -f spice_style.html
+	rm -f vd_interfaces.html
diff --git a/docs/vd_interfaces.txt b/docs/vd_interfaces.txt
new file mode 100644
index 00000000..2a01b8c7
--- /dev/null
+++ b/docs/vd_interfaces.txt
@@ -0,0 +1,388 @@
+VD Interfaces V0.1
+==================
+
+Draft 1
+
+Copyright (C) 2009 Red Hat, Inc.
+Licensed under a Creative Commons Attribution-Share Alike 3.0
+United States License (see http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
+
+Introduction
+------------
+
+Virtual Device Interfaces (VDI) provide a standard way to publish interfaces of virtual devices by
+a software component. This enables other software components to interact with these devices.
+This also enables other software components to interact with these devices. Going forward, the first
+component will be called the back-end and the second component will be called the front-end.
+An example for using Virtual Device Interfaces is as part of a virtual machine system,
+where the back-end will be the hardware emulation layer. The back-end will expose interfaces like
+display port, mouse input etc. The front-end will plug into the display output and will render its
+output according to it's specific implementation. The front-end will also plug into the mouse input
+and send mouse events to be processed by the back-end. In addition many other interface types
+can be exposed by the back-end. Another example of back-end is a remote display system in a physical
+machine environment. Here, the back-and is implemented using known techniques for interacting
+with the native OS for the purpose of receiving display updates and pushing inputs. The back-end
+exposes interfaces like display output, mouse input etc. The front-end can be exactly the same
+as in the previous example.
+
+By using VDI one back-end can use many types of front-ends without any special code modification.
+It is also possible for the back-end to dynamically switch front-ends, and improve back-end
+usability and flexibility. The use of front-ends by many back-ends allows for a better sharing of
+development, maintenance, and overall product quality.
+
+Basic operation
+---------------
+
+Back-end to front-end interaction is initiated by back-end. Back-end uses VDI_init symbol to pass
+its Core interface to the front-end. In addition to core interface, back-end also passes options
+argument to the front-end. Options argument is a string holding initialization argument specific
+to front-end implementation. Core interface, like every other interface in VDI, is represented
+as a data structure containing data members and member functions. Every interface starts with
+a common base structure “VDInterface”. The common structure contains information for identifying
+the type of the interface and the instance within the type group (i.e. The actual unique
+is {type, id}). Core interface provides basic functionality for attaching with other interfaces that
+the back-end implements. Core interface provides methods for receiving interface change events
+(i.e. interface added event and removing interface event) and for enumerating registers.
+Using these services, the front-end can find and interact with other interfaces that back-end
+publishes. The front-end uses VDI type for knowing what functionality the interface provides and
+the means to interact with the interface (i.e interface specific logic function and data members).
+
+Front-end public symbols
+------------------------
+
+VDI defines a minimal set of external symbols for enabling back-end to initiate with the front-end.
+The back-end can load front-end and retrieve front-end external symbols dynamically at run-time
+using native platform services. Alternatively, the front-end static or shared library can be linked
+to the back-end during back-end build process. 
+
+[source,c]
+int VDI_init(const char *args, CoreInterface *core)
+
+Front-and initialization function. The first parameter is options argument, the content of which
+depends on the specific front-end. The second parameter is core interface that provides the basic
+communication channel between front-end and back-end, core interface will be explained later on.
+VDI_init return value is VDI_ERROR_?
+
+[source,c]
+const char **VDI_get_usage()
+
+This function return array of strings in human readable form for displaying the available options
+argument that can be pass in args parameter of VDI_init call.
+
+Front-end termination
+---------------------
+
+No explicit symbol is defined for front-end termination. Removing core interface by back-end
+implicitly instructs front end to terminate itself. 
+
+Common Definition
+-----------------
+
+ * VDI_ERROR_OK = 0
+ * VDI_ERROR_ERROR = -1
+ * VM_INTERFACE_VERSION = 2. Current VDI version, front-end an back-end must have the same VDI
+ version for proper operation.
+ * VDIObjectRef – opaque object reference that passes between back-end and front-end
+ * VDI_INVALID_OBJECT_REF = 0
+
+Base structure of VD interface.
+-------------------------------
+
+The following is definition of VD Interface, all VDI interfaces are derived from VD Interface:
+
+ * UINT32 version - VDI version must be VM_INTERFACE_VERSION
+ * CONST  CHAR *type - type of the interface
+ * UNSIGNED INT id - unique id of the interface
+ * CONST  CHAR *description - interface human readable interface description
+ * UINT32 major_version - interface major version. Front-end and back-end interfaces having
+ different  major_version are not compatible.
+ * UINT32 minor_version - interface minor version. Minor version increments on changes that add
+ functionality but do not break compatible and will be reset on major version increment.
+
+Core interface
+--------------
+
+Core interface is the main interface for front-end to back-end communication. It is not allowed
+to have more the one interface with this type. Removal of Core interface by the back-end
+is explicit front-end termination.
+
+VDInterface members value
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[types]]
+Types
+~~~~~
+
+1.  
+
+[[vdinterface-specific-extension]]
+VDInterface specific extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* ** *** VDInterface *(* **next**)(CoreInterface *core, VDInterface
+*prev)
++
+
+1.  1.  
+
+* ** *** VDIObjectRef (***register_change_notifier**)(CoreInterface
+*core, void *opaque,
+
+1.  
+
+* ** *** void (***unregister_change_notifiers**)(CoreInterface *core,
+VDObjectRef notifier)
++
+
+1.  1.  
+
+1.  
+
+* ** *** VDIObjectRef (***create_timer**)(CoreInterface *core,
+timer_callback_t callback,
++
+ void* opaque)
++
++
+Create timer object. The timer handler will call callback on time
+expiration. opaque will be pushed back by back-end in callback call. On
+success the function return timer object ref otherwise
+VDI_INVALID_OBJECT_REF is returned.
+
+* ** *** void (***arm_timer**)(CoreInterface *core, VDIObjectRef timer,
+uint32_t ms)
++
++
+Schedule timer object to fire it's callback after ms. Timer is VDI ref
+object returned by create_timer and ms is time in millisecond.
+
+* ** *** void (***disarm_timer**)(CoreInterface *core, VDIObjectRef
+timer)
++
++
+Cancel previous *arm_timer scheduling.* Timer is VDI ref object returned
+by create_timer
++
+*** void (***destroy_timer**)(CoreInterface *core, VDIObjectRef timer)
++
++
+Destroy timer object. Timer is vdi ref object returned by create_timer.
+
+1.  
+
+* ** *** int (***set_file_handlers**)(CoreInterface *core, int fd, void
+(*on_read)(void *),
++
+ void (*on_write)(void *), void *opaque)
++
++
+Request notification on file descriptor for non blocking operation. Fd
+is the target file descriptor. Back-end will call on_read, if not NULL,
+on read events passing opaque as first argument. Back-end will call
+on_write, if not NULL, on write events passing opaque as first argument.
+On success VDI_ERROR_OK is return.
+
+1.  
+
+* ** *** void (***term_printf**)(CoreInterface *core, const char*
+format, ...)
++
+
+1.  1.  
+
+* ** *** void (***log**)(CoreInterface *core, LogLevel level, const
+char* component,
++
+ const char* format, ...)
++
+
+1.  1.  
+
+[[other-interfaces]]
+*Other interfaces*
+------------------
+
+[[keyboard-interface]]
+Keyboard interface
+------------------
+
+[[vdinterface-members-value-1]]
+VDInterface members value
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[types-1]]
+Types
+~~~~~
+
+1.  
+
+[[vdinterface-specific-extension-1]]
+VDInterface specific extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+* ** *** void (***push_scan_freg**)(KeyboardInterface *keyboard, uint8_t
+frag)
++
++
+Push scan-code code fragment to the keyboard. Frag is part of scan code.
+For example calling push_scan_freg(0xe0) push_scan_freg(0x1d) will
+result with Right CTRL.
++
+*** uint8_t (***get_leds**)(KeyboardInterface *keyboard)
++
++
+Get current keyboard lads mask. Return lads mask (see lesd in 8.2)
++
+*** VDIObjectRef (***register_leds_notifier**)(KeyboardInterface
+*keyboard,
++
+ keyboard_leads_notifier_t notifier,
++
+ void *opaque)
++
++
+Register for LED notification. Back-end will call notifier on every
+keyboard LED change. Opaque will be pushed back as notifier argument. On
+success, the function return notifier object ref otherwise
+VDI_INVALID_OBJECT_REF is returned.
++
+*** void (***unregister_leds_notifier**)(KeyboardInterface *keyboard,
+VDObjectRef notifier)
++
+
+1.  1.  
+
+[[mouse-interface]]
+Mouse interface
+---------------
+
+[[vdinterface-members-value-2]]
+VDInterface members value
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[types-2]]
+Types
+~~~~~
+
+[[vdinterface-specific-extension-2]]
+VDInterface specific extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+* ** *** void (***motion**)(MouseInterface* mouse, int dx, int dy, int
+dz, uint32_t buttons_state)
++
++
+Push mouse motion and buttons state. dx and dy are mouse motion in
+pixels in x and y axis, positive dx is rightward motion and positive dy
+is downward motion. dz is scroll wheel ticks, positive value is scroll
+down. buttons_state is buttons state mask. Button X is press if bit
+VDI_MOUSE_BUTTON_X is set.
+
+* ** *** void (***buttons**)(MouseInterface* mouse, uint32_t
+buttons_state)
++
++
+Push mouse buttons state. buttons_state is the same as in the motion
+call
+
+1.  1.  
+
+[[tablet-interface]]
+Tablet interface
+----------------
+
+[[interface-members-value]]
+Interface members value
+~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[types-3]]
+Types
+~~~~~
+
+[[vdinterface-specific-extension-3]]
+VDInterface specific extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[playback-interface]]
+Playback interface
+------------------
+
+[[vdinterface-members-value-3]]
+VDInterface members value
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[playbackplug]]
+*PlaybackPlug*
+~~~~~~~~~~~~~~
+
+1.  
+
+[[vdinterface-specific-extension-4]]
+VDInterface specific extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+1.  1.  
+
+1.  
+
+[[record-interface]]
+Record interface
+----------------
+
+[[vdinterface-members-value-4]]
+VDInterface members value
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+[[recordplug]]
+RecordPlug
+~~~~~~~~~~
+
+1.  
+
+1.  
+
+[[vdinterface-specific-extension-5]]
+VDInterface specific extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1.  
+
+1.  1.  
+
+1.  
+
+[[additional-registered-interfaces]]
+Additional registered interfaces
+--------------------------------
+
+* ** QXL interface "qxl" – QXL interface enable front-end to plug into
+QXL display device in order to receive QXL and to render it's output
+locally or remotely.
+** VDI port interface "vdi_port" – interface for plugging, reading and
+writing to vdi_port. vdi_port is used for communication with an agent
+residing on gust machine.
+** Migration interface "migration" - interface for integrating with
+back-end migration process. This interface enable registering for pre
+and post migration hooks.
+** Qemu terminal interface "qemu_terminal" – interface for integrating
+with QEMU style terminal.