File	Date	Author	Commit
src	2015-01-06	MrCompiler	[ad4273] Add basic support for mapping PCI memory
README.txt	2014-10-14	Eugene Snider	[8841c3] Added build information to the README

Read Me

NOTE: This code is still pre-alpha and may not fully reflect the state of
the distributed development repositories.

MQNIC ( Message Queue NIC ) Virtual Link Layer

The Message Queue NIC project provides a virtual link layer for qemu/kvm based
virtual machines. The virtual link layer provides transport using the
Apache ActiveMQ message server or other message bus and eliminates the
need for external IP infrastructure to support VM deployments.

Based on the ivshmem technology originally developed by Cam Macdonell
the mqnic drivers use zero copy vm<->host data transfers and the apache
message server to provide low latency, high bandwidth IP support for
virtual data centers while simplifying the provisioning of hosted IP.

Because the Message Queue NIC appears as a standard IP device on the target
machine the integration of MQNIC and traditional IP routing is completely
managed by the standard IP routing tools and infrastructure.

Transport security is handled by the MQ server which supports multiple
levels of encryption and authentication. Additionally unlike traditional
ethernet transport the customer data is highly segregated.

Multiple servers can be configured in a redundant configuration to
provide high availability support.

How it works:

The mqnicd runs on the hosting platform. It is started. The daemon
allocates the global shared memory and establishes contact with the
ActiveMQ server. It also creates a socket which will be used for
communicating with the virtual machines.

It also creates a VM ID number 0 which is used to recieve and
transmit event notifications for customer VMs. The mqnic driver
in a customer VM notifies the host server that a transmit packet
is ready by using the ivshmem 'doorbell' signal.

The qemu emulator is launched with the necessary arguments to create
the socket connection and initialize the ivshmem driver. This creates
a pseudo-device that is used by the mqnic device driver.

Once the VM has booted the mqnic driver must be loaded with 'insmod' or 
some other suitable utility. This establishes contact with the ivhsmem
driver and sets up the global shared buffer space that will be used for
transmit and recieve operations.

It also creates 1-4 network devices ( /dev/mqnic{0-3} ). These are
fully configurable network devices, the mac addresses are provisionable but
must be unique across the mqnic network space. The arp protocol is not
supported.

The configuration information for the nics is stored in the global space
where it is accessible to the server.

When the host server recieves the new connection it creates message queues
on the apache server for the target NICs and sets up a listener to monitor
events.

When a user application attempts to send a message the mqnic driver obtains a
buffer from the global pool and the user message is copied into it. The
mqnic driver notifies the host via the ivshmem 'doorbell' that a transmit
is pending.

The mqnic driver then blocks until notified that the transmit has been
completed.

The host server obtains the destination mac address from the transmit frame
which is used as the destination queue name on the MQ server. These
messages can be optionally be configured for guaranteed delivery and
persistance for support of fail over in high availability scenarios.

In any case the results are reported back to the customer VM mqnic using
the ivshmem event notification fds.

When a new message is posted to a destination queue for one of the owned
NICs the listening agent obtains a buffer from the global shared memory
space and copies the message contents into it. It extracts the destination
ethernet address and identifies the customer VM which owns this address. It
then notifies the mqnic that a recieve packet is pending using the ivshem
event notification fds.

How to build:

You will need to get, build and install the activemq-cpp source. The server makefile expects to find this at the same level as the mqnic code.
To get the source use:

git clone https://git-wip-us.apache.org/repos/asf/activemq-cpp.git

You will need this list of packages to build 

autoconf
automake
libtool
libcppunit-dev
libapr1-dev
libssl-dev
libnet1-dev

These can be installed with 'apt-get' for Ubuntu or 'yum' for Fedora.

After you've got everything install cd to active-mq/active-mq directory and
type ./autogen.sh. This will generate a number of warnings which can be
safely ignored (I think).

Once autogen completes run configure, then make and make install.

This will install the activemq-cpp files into /usr/local

Now you can compile mqnic. For testing create a virtual machine by some
mechanism and start QEMU with the socket and ivshmem options.


cd into src/driver and run make the cd into src/server and run make.