/*! \mainpage KIM KVM API documentation
 * 
 * \section intro Introduction 
 * 
 *
 * This documentation describes the API used to access Peppercon KVM hardware.
 * It describes all major functions and parts needed to implement an encoder
 * like Peppercons RFB protocoll or Raritan TRServer.
 * 
 * Please note that this documentation is not complete and work in progress.
 * Currently only the KVM API is covered although we plan to integrate other
 * important software modules in the future.
 * 
 * \section note Historical note
 * 
 * This documentation is derived from the libpp_adap, a first approach to adapt
 * Peppercon functionality for Raritan products. This proved to be neither
 * flexible nor good to maintain, so we decided to take a different approach.
 * Instead of encapsulating all functionality in one adapter, we will split
 * important parts from the firmware and build independant and well documented
 * modules.
 * 
 * The major advantage of this approach is that Peppercon and Raritan will use
 * the same sourcecode that is well tested and under constant observation. Also
 * any necessary bugfixes and improvements will be available immediately.
 * 
 * \section overview Overview
 * 
 * This section provides a coarse overview over the existing modules and their
 * functions.
 *
 * The main modules are:
 *    - Grabber: provides framebuffers of the grabbed video and change notification and information.
 *    - VSC: deals with recognizing and adjusting the video signal so that it can be grabbed.
 *    - KM: deals with emulating keyboard and mouse devices
 *    - Property change listener: notifies of  keyboard led status changes and vsc mode changes.
 *
 * We recommend the <a href="files.html">Files Section</a> as
 * the starting point for browseing this documentation.
 *
 * \section kvm Video grabber API details
 * 
 * The Video grabber is a complex API that covers two different hardwares. The first type
 * of hardware ist the VSC1. A VSC1 can be found on all KIMs and implements a simple
 * framebuffer that consists of raw hextiles. The second supported hardware is the VSC2.
 * It is no longer a simple framebuffer but supports client-specific, pre-encoded buffers.
 * The VSC2 is embedded in KIRA and some other products (mostly peppercon IPMI cards).
 * Both VSC1 and VSC2 support the generation of 'diffmaps' that show which parts of the
 * framebuffer have changed.
 * 
 * In times of libpp_adap, only the VSC1 existed. Since then, the API has changed
 * significantly. The most important change is that the API now knows the concept
 * of 'clients' that may have individual settings and buffers. The second big change
 * is that the diffmap handling is now a part of the grabber, not of the encoder.
 * 
 * As the hardware capabilities of VSC1 and VSC2 differ significantly, some functions
 * of the API have different functionality depending on the used hardware. In 'pp/features.h'
 * there is a define called 'PP_FEAT_VSC_HW_ENCODING' that marks hardware with a VSC2.
 * Depending on this define, some functions of the API have to be used differently.
 * This will be noted when explaining the corresponding function.
 * 
 * <h3>How to use the new API (grabber, vsc)</h3>
 * 
 * The basic initialization of the framegrabber and the video sampling controller
 * is the same as in libpp_adap. Call xxx_init() in both libraries, connect the 
 * encoder and call pp_grab_start(). The system is now ready to use.
 * 
 * Now assume that a client connects to the encoder. The encoder announces 
 * the new client at the grabber (pp_grab_new_client()). As a result, he
 * gets a client structure that identifies the client. The encoder then sets the
 * client specific encoding parameters with pp_grab_set_encoding(). As the VSC1
 * does not support client-specific encodings, this operation is a 'noop' on VSC1
 * hardware (and can be left away). After that, the client is ready to receive
 * updates.
 * 
 * Whenever a new frame is available in the framebuffer, the diffmap for this
 * frame will be calculated (call it the 'global' diffmap). The grabber calls both 
 * new_diffmap_available() and new_data_available() to notify the encoder that a new 
 * frame is available. 
 * In addition, each client has an individual internal diffmap that accumulates the 
 * hextiles that have changed since the last client request for data.
 * 
 * The encoder now distributes this information internally until at some point
 * a client(thread) decides to process the new data. The client requests the data
 * from the grabber by calling pp_grab_request_region() or pp_grab_request_rect().
 * After the request returns, the requested data is available in client_struct->buf.
 *
 * The details of diffmap handling differ between VSC1 and VSC2 devices.
 * For VSC2 the region considered for transfer is an intersection between the requested
 * region and an union between the current global and accumulated client-local 
 * internal diffmap.
 * As the size of the transferred data is not yet known before the actual encoding, 
 * the grabber splits the requested region in a way that the buffer is able to
 * contain the whole request in the worst case. The first part (returned as 'ack') 
 * contains all hextiles that have changed and were part of the requested region. 
 * The second part (returned as 'remain') contains all remaining hextiles that have 
 * changed and were requested but could not be transferred during the current run 
 * because of these buffer size restrictions. The remaining diffmap is stored as the 
 * new internal client diffmap. 
 * There is a flag to ignore the internal diffmap and return the largest possible part of
 * the whole requested region instead. Please note that the size restrictions and 
 * splitting process remains even in this case.
 * 
 * The advantage of this approach is that clients do not have to keep track of
 * their diffmaps themselves. Instead they can just request the regions they need.
 * 
 * For VSC1 devices the diffmap handling is more simple. Here pp_grab_request_region()
 * returns the intersection of the requested region and the current diffmap of a 
 * client as the 'ack' region. The 'remain' region is unused as there are no
 * buffer size restrictions and the whole framebuffer is always available.
 * Clients again do not have to keep track of their diffmap, they just get it
 * from the grabber during a request.
 *
 * A request resets the acknowledged part of the client-local internal diffmap for the 
 * next request. This works even if the processing of the current diffmap takes longer 
 * and several diffmap updates arrive until the next request.
 *
 * The data that is available in the client structure after a request depends
 * on the hardware once again. For VSC1, the buffer always contains the full raw
 * framebuffer as in earlier version of the grabberlib. Clients have to retrieve
 * the hextiles from this buffer themselves, preferably using the list returned
 * with the request.
 * 
 * For VSC2, the buffer contains exactly the regions that are returned in 'ack'.
 * Additionally these regions are encoded in HW. Each region is prefixed with a
 * vsc_update_rect_hdr_t (see lara_kernel_modules/lara.h) followed by the specified
 * amount of data. The encoding details of the data can be found in the vsc
 * specification (download module 'vsc' from peppercon repository and check directory
 * 'doc'). The buffer in VSC2 is an allocated structure that must be freed with
 * pp_grab_release_buffer() after using it (possibly encoding it and sending it to the 
 * network).
 * 
 * \image html grab_seq.png
 *
 * \section chglog Change log
 *    - 0.1: 
 *      - initial draft
 *    - 0.2:
 *      - added sequence diagrams of grabber initialization and operation
 *      - added description of pointer synchronization magic 
 *      - added MISC library and reboot API
 *      - some more small fixes
 *    - 0.3:
 *      - change function names from rr_* to pa_* 
 *      - add interface to handle regions
 *      - some minor interface changes
 *      - change internal libs to implement the adapter interfaces
 *      - change encoder (liberic_rfb) to use the interface lib -> pending
 *    - 0.4:
 *      - move functionality to libpp_vsc, libpp_grab, libpp_km
 *      - integrated changes for VSC2
 *      - removed libpp_adap
 *      - rewrote documentation
 *
 * (c) 2004 Peppercon AG, miba@peppercon.de, tbr@peppercon.de, mkl@peppercon.de, geo@peppercon.de
 */
