		CPINT HOW-TO
		------------

These three device drives provide the ability for a calling program to:

1. Issue VM commands and receive their responses
2. Cut VM APPLDATA monitor records
3. Cut VM accounting records

All the drivers are 32 and 64-bit enabled. In addition multiple programs can concurrently
uses the devices. By default, the devices are only usable by "root" but this can be
changed by altering the device ownership/permission characteristics.

The drivers require the use of scripts to load (cpint_load) and unload (cpint_unload) as
they use the "experimental" device major node number.

The driver will also check for the presence of VM when loaded and will return -EACCES if
it's not detected.

Building Device Driver
----------------------

Issue the following command to build the driver module:

 make -C /lib/modules/`uname -r`/build M=`pwd` SUBDIRS=`pwd` modules

Building Tools
---------------

Issue the following command to build the commands like hcp:

 make tools

Installation
------------

Issue the "make install" command from the superuser. 

VM Command (cpcmd)
------------------

This driver is used to allow an authorized program (based on device ownership) to issue
command(s) to be executed by the VM hypervisor, read the results, and retrieve the
return code. To perform these activities a program uses:

1. write() to get VM to execute the command
2. read() to retrieve the results of executing the command
3. ioctl() to retrieve the return code.

See the source of hcp.c in this package for an example of how to use these calls.

Monitor Records (cpmon)
-----------------------

To use the Linux guest requires OPTION APPLDATA in its VM directory entry.

This driver is used to allow an application to "cut" APPLDATA monitor records. The 
application is able to generate event records or place records into a sample buffer that
VM will interrogate according to the sample interval. An application my specify a
product id to accompany any of the records cut. To perform these activities a program
uses:

1. write() to send a command and data buffer to the driver. The command/data buffer 
   takes the format:
	struct monData {
	   char fcn;
	   char len;
	   char data[APPLMON_BUFSIZE];
	} *monData;
   where:
	fcn  - Function code:
		APPLMON_START_REC - start interval recording
		APPLMON_STOP_REC  - stop interval/configuration recording
		APPLMON_GEN_EVENT - generate an event record
		APPLMON_START_CON - start configuration recording
		APPLMON_PUT_SAMP  - place record in the sample buffer

	len  - Length of record in the data variable

	data - Monitor record data

2. ioctl() to specify the product id to be used for this recording

VM is able to cope with multiple sample buffers and so multiple applications can use
this driver concurrently. See the source of monstat.c and mongen.c for examples of
how to use these calls.

Account Records (cpact)
-----------------------

To use the Linux guest requires OPTION ACCOUNT in its VM directory entry.

This driver is used to allow an application to "cut" VM accounting records. These records
are 70 bytes long and attempts to write longer records will result in truncation and
the count returned will indicate this. To perform the record cutting a program uses the
write() call.

For an example of how to use this call refer to actgen.c.
