1b5850970SChris LukeVector Packet Processing
2b5850970SChris Luke========================
3b5850970SChris Luke
4f3045526SChris Luke## Introduction
5b5850970SChris Luke
6b5850970SChris LukeThe VPP platform is an extensible framework that provides out-of-the-box
7b5850970SChris Lukeproduction quality switch/router functionality. It is the open source version
8b5850970SChris Lukeof Cisco's Vector Packet Processing (VPP) technology: a high performance,
9b5850970SChris Lukepacket-processing stack that can run on commodity CPUs.
10b5850970SChris Luke
11b5850970SChris LukeThe benefits of this implementation of VPP are its high performance, proven
12b5850970SChris Luketechnology, its modularity and flexibility, and rich feature set.
13b5850970SChris Luke
14b5850970SChris LukeFor more information on VPP and its features please visit the
15b5850970SChris Luke[FD.io website](http://fd.io/) and
16b5850970SChris Luke[What is VPP?](https://wiki.fd.io/view/VPP/What_is_VPP%3F) pages.
17b5850970SChris Luke
18b5850970SChris Luke
19f3045526SChris Luke## Changes
20f3045526SChris Luke
21f3045526SChris LukeDetails of the changes leading up to this version of VPP can be found under
22f3045526SChris Luke@ref release_notes.
23f3045526SChris Luke
24f3045526SChris Luke
25f3045526SChris Luke## Directory layout
26b5850970SChris Luke
27159fcf40SChris Luke| Directory name         | Description                                 |
28159fcf40SChris Luke| ---------------------- | ------------------------------------------- |
29159fcf40SChris Luke|      build-data        | Build metadata                              |
30159fcf40SChris Luke|      build-root        | Build output directory                      |
31159fcf40SChris Luke|      doxygen           | Documentation generator configuration       |
32159fcf40SChris Luke|      dpdk              | DPDK patches and build infrastructure       |
33159fcf40SChris Luke| @ref extras/libmemif   | Client library for memif                    |
34159fcf40SChris Luke| @ref src/examples      | VPP example code                            |
35159fcf40SChris Luke| @ref src/plugins       | VPP bundled plugins directory               |
36159fcf40SChris Luke| @ref src/svm           | Shared virtual memory allocation library    |
37159fcf40SChris Luke|      src/tests         | Standalone tests (not part of test harness) |
38159fcf40SChris Luke|      src/vat           | VPP API test program                        |
39159fcf40SChris Luke| @ref src/vlib          | VPP application library                     |
40159fcf40SChris Luke| @ref src/vlibapi       | VPP API library                             |
41159fcf40SChris Luke| @ref src/vlibmemory    | VPP Memory management                       |
42159fcf40SChris Luke| @ref src/vnet          | VPP networking                              |
43159fcf40SChris Luke| @ref src/vpp           | VPP application                             |
44159fcf40SChris Luke| @ref src/vpp-api       | VPP application API bindings                |
45159fcf40SChris Luke| @ref src/vppinfra      | VPP core library                            |
46159fcf40SChris Luke| @ref src/vpp/api       | Not-yet-relocated API bindings              |
47159fcf40SChris Luke|      test              | Unit tests and Python test harness          |
48b5850970SChris Luke
49f3045526SChris Luke## Getting started
50b5850970SChris Luke
51b5850970SChris LukeIn general anyone interested in building, developing or running VPP should
52b5850970SChris Lukeconsult the [VPP wiki](https://wiki.fd.io/view/VPP) for more complete
53b5850970SChris Lukedocumentation.
54b5850970SChris Luke
55b5850970SChris LukeIn particular, readers are recommended to take a look at [Pulling, Building,
56b5850970SChris LukeRunning, Hacking, Pushing](https://wiki.fd.io/view/VPP/Pulling,_Building,_Run
57b5850970SChris Lukening,_Hacking_and_Pushing_VPP_Code) which provides extensive step-by-step
58b5850970SChris Lukecoverage of the topic.
59b5850970SChris Luke
60b5850970SChris LukeFor the impatient, some salient information is distilled below.
61b5850970SChris Luke
62b5850970SChris Luke
63f3045526SChris Luke### Quick-start: On an existing Linux host
64b5850970SChris Luke
65b5850970SChris LukeTo install system dependencies, build VPP and then install it, simply run the
66b5850970SChris Lukebuild script. This should be performed a non-privileged user with `sudo`
67b5850970SChris Lukeaccess from the project base directory:
68b5850970SChris Luke
6948009e4cSDamjan Marion    ./extras/vagrant/build.sh
70b5850970SChris Luke
71b5850970SChris LukeIf you want a more fine-grained approach because you intend to do some
72b5850970SChris Lukedevelopment work, the `Makefile` in the root directory of the source tree
73b5850970SChris Lukeprovides several convenience shortcuts as `make` targets that may be of
74b5850970SChris Lukeinterest. To see the available targets run:
75b5850970SChris Luke
76b5850970SChris Luke    make
77b5850970SChris Luke
78b5850970SChris Luke
79f3045526SChris Luke### Quick-start: Vagrant
80b5850970SChris Luke
8148009e4cSDamjan MarionThe directory `extras/vagrant` contains a `VagrantFile` and supporting
82b5850970SChris Lukescripts to bootstrap a working VPP inside a Vagrant-managed Virtual Machine.
83b5850970SChris LukeThis VM can then be used to test concepts with VPP or as a development
84b5850970SChris Lukeplatform to extend VPP. Some obvious caveats apply when using a VM for VPP
85b5850970SChris Lukesince its performance will never match that of bare metal; if your work is
86b5850970SChris Luketiming or performance sensitive, consider using bare metal in addition or
87b5850970SChris Lukeinstead of the VM.
88b5850970SChris Luke
89b5850970SChris LukeFor this to work you will need a working installation of Vagrant. Instructions
90b5850970SChris Lukefor this can be found [on the Setting up Vagrant wiki page]
91b5850970SChris Luke(https://wiki.fd.io/view/DEV/Setting_Up_Vagrant).
92b5850970SChris Luke
93b5850970SChris Luke
94f3045526SChris Luke## More information
95b5850970SChris Luke
965ccbaa97SChris LukeSeveral modules provide documentation, see @subpage user_doc for more
9764ebb5ffSChris Lukeend-user-oriented information. Also see @subpage dev_doc for developer notes.
985ccbaa97SChris Luke
99b5850970SChris LukeVisit the [VPP wiki](https://wiki.fd.io/view/VPP) for details on more
10064ebb5ffSChris Lukeadvanced building strategies and other development notes.
101c8c5335eSDave Wallace
102c8c5335eSDave Wallace
103c8c5335eSDave Wallace## Test Framework
104c8c5335eSDave Wallace
10564ebb5ffSChris LukeThere is PyDoc generated documentation available for the VPP test framework.
10664ebb5ffSChris LukeSee @ref test_framework_doc for details.