1 files changed, 94 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 00000000000..2a71d27e10e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,94 @@
+Vector Packet Processing
+========================
+
+## Introduction.
+
+The VPP platform is an extensible framework that provides out-of-the-box
+production quality switch/router functionality. It is the open source version
+of Cisco's Vector Packet Processing (VPP) technology: a high performance,
+packet-processing stack that can run on commodity CPUs.
+
+The benefits of this implementation of VPP are its high performance, proven
+technology, its modularity and flexibility, and rich feature set.
+
+For more information on VPP and its features please visit the
+[FD.io website](http://fd.io/) and
+[What is VPP?](https://wiki.fd.io/view/VPP/What_is_VPP%3F) pages.
+
+
+## Directory layout.
+
+Directory name         | Description
+---------------------- | -------------------------------------------
+     build-data        | Build metadata
+     build-root        | Build output directory
+     doxygen           | Documentation generator configuration
+     dpdk              | DPDK patches and build infrastructure
+     g2                | Event log visualization tool
+     gmod              | perf related?
+     perftool          | Performance tool
+     sample-plugin     | A sample plugin
+@ref svm               | Shared virtual memory allocation library
+     test              | Unit tests
+@ref vlib              | VPP application library source
+@ref vlib-api          | VPP API library source
+@ref vnet              | VPP networking source
+@ref vpp               | VPP application source
+@ref vpp-api           | VPP application API source
+     vppapigen         | VPP API generator source
+     vpp-api-test      | VPP API test program source
+@ref vppinfra          | VPP core library source
+
+(If the page you are viewing is not generated by Doxygen then
+ignore any @@ref labels in the above table.)
+
+
+## Getting started.
+
+In general anyone interested in building, developing or running VPP should
+consult the [VPP wiki](https://wiki.fd.io/view/VPP) for more complete
+documentation.
+
+In particular, readers are recommended to take a look at [Pulling, Building,
+Running, Hacking, Pushing](https://wiki.fd.io/view/VPP/Pulling,_Building,_Run
+ning,_Hacking_and_Pushing_VPP_Code) which provides extensive step-by-step
+coverage of the topic.
+
+For the impatient, some salient information is distilled below.
+
+
+### Quick-start: On an existing Linux host.
+
+To install system dependencies, build VPP and then install it, simply run the
+build script. This should be performed a non-privileged user with `sudo`
+access from the project base directory:
+
+    ./build-root/vagrant/build.sh
+
+If you want a more fine-grained approach because you intend to do some
+development work, the `Makefile` in the root directory of the source tree
+provides several convenience shortcuts as `make` targets that may be of
+interest. To see the available targets run:
+
+    make
+
+
+### Quick-start: Vagrant.
+
+The directory `build-root/vagrant` contains a `VagrantFile` and supporting
+scripts to bootstrap a working VPP inside a Vagrant-managed Virtual Machine.
+This VM can then be used to test concepts with VPP or as a development
+platform to extend VPP. Some obvious caveats apply when using a VM for VPP
+since its performance will never match that of bare metal; if your work is
+timing or performance sensitive, consider using bare metal in addition or
+instead of the VM.
+
+For this to work you will need a working installation of Vagrant. Instructions
+for this can be found [on the Setting up Vagrant wiki page]
+(https://wiki.fd.io/view/DEV/Setting_Up_Vagrant).
+
+
+## More information.
+
+Visit the [VPP wiki](https://wiki.fd.io/view/VPP) for details on more
+advanced building strategies and development notes.