update example for 1.1

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## [Unreleased]
+### Added
+- Updated the example to reflect the new build system
+- Updated documentation
+
 ## [1.0.0] - 2016-04-05
 ### Added
 - Initial Example

Makefile → Makefile.bf

@@ -24,10 +24,9 @@
 ################################################################################
 
 PARENT_SUBDIRS += vcpu_factory_msr_bitmap
-PARENT_SUBDIRS += vmcs_msr_bitmap
 
 ################################################################################
 # Common
 ################################################################################
 
-include ../common/common_subdir.mk
+include %HYPER_ABS%/common/common_subdir.mk

README.md

@@ -1,46 +1,44 @@
-# Bareflank Hypervisor Example
+# Bareflank Hypervisor MST Bitmap Example
 
 ## Description
 
-This example demonstrates how to extend the Bareflank hypervisor to utilize the MSR bitmap feature of Intel virtualization. For more information on how Bareflank extensions work, please see the following:
+This example demonstrates how to extend the Bareflank hypervisor to use
+Intel's MSR Bitmap to increase performance. For more information on how
+Bareflank extensions work, please see the following:
 
 [API Documentation](http://bareflank.github.io/hypervisor/html/)
 
 ## Compilation / Usage
 
-First, you must clone the repo into your existing Bareflank repo. To see instructions on how to setup Bareflank, please see the following:
-
-[Bareflank Hypervisor](https://github.com/Bareflank/hypervisor)
-
-At the moment, out-of-tree compilation is not supported.
+To setup our extension, run the following (assuming Linux):
 
 ```
+cd ~/
+git clone https://github.com/Bareflank/hypervisor.git
+git clone https://github.com/Bareflank/hypervisor_example_msr_bitmap.git
 cd ~/hypervisor
-git clone https://github.com/Bareflank/hypervisor_example_msr_bitmap
-```
 
-Once the example repo is cloned, you can now build the example. Bareflank automatically looks for the examples, or any folder that starts with "src_", and builds these folders along with Bareflank itself. 
+./tools/scripts/setup-<xxx>.sh --no-configure
+sudo reboot
 
-```
+cd ~/
+mkdir build
+cd ~/build
+
+~/hypervisor/configure -m ~/hypervisor_example_msr_bitmap/bin/msr_bitmap.modules -e ~/hypervisor_example_msr_bitmap
 make
 ```
 
-Finally, you can run the example. This can be done by running bfm manually, and providing the path to your custom modules list:
+To test out our extended version of Bareflank, all we need to do is run the
+make shortcuts as usual:
 
 ```
-pushd bfm/bin/native
-sudo LD_LIBRARY_PATH=. ./bfm load hypervisor_example_msr_bitmap/bin/msr_bitmap.modules
-sudo LD_LIBRARY_PATH=. ./bfm start
-sudo LD_LIBRARY_PATH=. ./bfm status
-sudo LD_LIBRARY_PATH=. ./bfm dump
-popd
-```
-
-or you can use the shortcuts:
+make driver_load
+make quick
 
-```
-make load MODULES=hypervisor_example_msr_bitmap/bin/msr_bitmap.modules
-make start
 make status
 make dump
+
+make stop
+make driver_unload
 ```

bin/msr_bitmap.modules

@@ -1,26 +1,23 @@
-################################################################################
-# Default Modules                                                              #
-################################################################################
-
-# Default Modules
-#
-# Note: The existing vcpu_factory module is commented out as we will be
-# providing our own.
-../../../bfvmm/bin/cross/libmemory_manager.so
-../../../bfvmm/bin/cross/libentry.so
-../../../bfvmm/bin/cross/libserial.so
-../../../bfvmm/bin/cross/libdebug_ring.so
-../../../bfvmm/bin/cross/libintrinsics.so
-../../../bfvmm/bin/cross/libvmxon.so
-../../../bfvmm/bin/cross/libvmcs.so
-../../../bfvmm/bin/cross/libvcpu.so
-#../../../bfvmm/bin/cross/libvcpu_factory.so
-../../../bfvmm/bin/cross/libexit_handler.so
-../../../bfvmm/bin/cross/libmisc.so
-../../../bfvmm/bin/cross/libc++.so
-
-# Custom Modules
-#
-# Note: This is where we provide our own vcpu_factory.
-../../../hypervisor_example_msr_bitmap/bin/cross/libvcpu_factory_msr_bitmap.so
-../../../hypervisor_example_msr_bitmap/bin/cross/libvmcs_intel_x64_msr_bitmap.so
+{
+    "modules" :
+    [
+        "%BUILD_ABS%/sysroot_vmm/x86_64-vmm-elf/lib/libc++.so.1.0",
+        "%BUILD_ABS%/sysroot_vmm/x86_64-vmm-elf/lib/libc++abi.so.1.0",
+        "%BUILD_ABS%/sysroot_vmm/x86_64-vmm-elf/lib/libc.so",
+        "%BUILD_ABS%/makefiles/bfunwind/bin/cross/libbfunwind.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/crt/bin/cross/libcrt.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/debug_ring/bin/cross/libdebug_ring.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/entry/bin/cross/libentry.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/exit_handler/bin/cross/libexit_handler.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/intrinsics/bin/cross/libintrinsics.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/memory_manager/bin/cross/libmemory_manager.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/misc/bin/cross/misc",
+        "%BUILD_ABS%/makefiles/bfvmm/src/pthread/bin/cross/libpthread.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/serial/bin/cross/libserial.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/syscall/bin/cross/libsyscall.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/vcpu/bin/cross/libvcpu.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/vmcs/bin/cross/libvmcs.so",
+        "%BUILD_ABS%/makefiles/bfvmm/src/vmxon/bin/cross/libvmxon.so",
+        "%BUILD_ABS%/makefiles/hypervisor_example_msr_bitmap/vcpu_factory_msr_bitmap/bin/cross/libvcpu_factory_msr_bitmap.so"
+    ]
+}

vcpu_factory_msr_bitmap/Makefile → vcpu_factory_msr_bitmap/Makefile.bf

@@ -29,4 +29,4 @@ SUBDIRS += src
 # Common
 ################################################################################
 
-include ../../common/common_subdir.mk
+include %HYPER_ABS%/common/common_subdir.mk

vcpu_factory_msr_bitmap/src/Makefile → vcpu_factory_msr_bitmap/src/Makefile.bf

@@ -1,5 +1,5 @@
 #
-# Bareflank Hypervisor Examples
+# Bareflank Hypervisor
 #
 # Copyright (C) 2015 Assured Information Security, Inc.
 # Author: Rian Quinn        <quinnr@ainfosec.com>
@@ -25,12 +25,24 @@
 
 TARGET_NAME:=vcpu_factory_msr_bitmap
 TARGET_TYPE:=lib
-TARGET_COMPILER:=cross
+
+ifeq ($(shell uname -s), Linux)
+    TARGET_COMPILER:=both
+else
+    TARGET_COMPILER:=cross
+endif
 
 ################################################################################
 # Compiler Flags
 ################################################################################
 
+NATIVE_CCFLAGS+=
+NATIVE_CXXFLAGS+=
+NATIVE_ASMFLAGS+=
+NATIVE_LDFLAGS+=
+NATIVE_ARFLAGS+=
+NATIVE_DEFINES+=
+
 CROSS_CCFLAGS+=
 CROSS_CXXFLAGS+=
 CROSS_ASMFLAGS+=
@@ -42,20 +54,21 @@ CROSS_DEFINES+=
 # Output
 ################################################################################
 
-CROSS_OBJDIR:=.build
-CROSS_OUTDIR:=../../bin
+CROSS_OBJDIR+=%BUILD_REL%/.build
+CROSS_OUTDIR+=%BUILD_REL%/../bin
+
+NATIVE_OBJDIR+=%BUILD_REL%/.build
+NATIVE_OUTDIR+=%BUILD_REL%/../bin
 
 ################################################################################
 # Sources
 ################################################################################
 
 SOURCES+=vcpu_factory_msr_bitmap.cpp
 
-INCLUDE_PATHS+=./
 INCLUDE_PATHS+=../../
-INCLUDE_PATHS+=../../vmcs_msr_bitmap
-INCLUDE_PATHS+=../../../include/
-INCLUDE_PATHS+=../../../bfvmm/include/
+INCLUDE_PATHS+=%HYPER_ABS%/include/
+INCLUDE_PATHS+=%HYPER_ABS%/bfvmm/include/
 
 LIBS+=
 
@@ -84,4 +97,4 @@ LINUX_LIBRARY_PATHS+=
 # Common
 ################################################################################
 
-include ../../../common/common_target.mk
+include %HYPER_ABS%/common/common_target.mk

vcpu_factory_msr_bitmap/src/vcpu_factory_msr_bitmap.cpp

@@ -21,34 +21,20 @@
 
 #include <vcpu/vcpu_factory.h>
 #include <vcpu/vcpu_intel_x64.h>
-#include <vmcs_intel_x64_msr_bitmap.h>
-#include <exit_handler_msr_bitmap/exit_handler_msr_bitmap.h>
+#include <vmcs_msr_bitmap/vmcs_msr_bitmap.h>
 
-std::shared_ptr<vcpu>
-vcpu_factory::make_vcpu(int64_t vcpuid)
+std::unique_ptr<vcpu>
+vcpu_factory::make_vcpu(vcpuid::type vcpuid, user_data *data)
 {
-    // The vCPU Factory is used by the vCPU Manager to create vCPUs. This not
-    // only provides a hook for unit testing (the classic factory pattern), but
-    // also provides a clever place to hook in custom functionality above and
-    // beyond what bareflank provides by default.
+    auto &&my_vmcs = std::make_unique<vmcs_msr_bitmap>();
 
-    // In this example, we are providing a custom exit handler that does not
-    // have any MSR emulation included.
-    auto exit_handler = std::make_shared<exit_handler_msr_bitmap>();
-
-    // Provide a custom VMCS that initializes the MSR bitmap
-    auto vmcs = std::make_shared<vmcs_intel_x64_msr_bitmap>();
-
-    // Now that we have our custom exit handler, we can provide it to the
-    // vCPU that bareflank provides. Note that you could create your own vCPU
-    // if you need to, but in general, the existing vCPU should work for most
-    // cases as it allows you to override each of the classes that are required.
-    // In all cases here, if nullptr is provided, the code under the hood will
-    // create the class for you using the defaults.
-    return std::make_shared<vcpu_intel_x64>(vcpuid,
-                                            nullptr,
-                                            nullptr,
-                                            vmcs,
-                                            exit_handler,
-                                            nullptr);
+    (void) data;
+    return std::make_unique<vcpu_intel_x64>(
+               vcpuid,
+               nullptr,                         // default debug_ring
+               nullptr,                         // default vmxon
+               std::move(my_vmcs),
+               nullptr,                         // default exit handler
+               nullptr,                         // default vmm_state
+               nullptr);                        // default guest_state
 }