/******************************************************************************
 * README                                                                     *
 * Authors: Megha Dey, Yu-Cheng Yu                                            *
 * Contact: megha.dey@intel.com, yu-cheng.yu@intel.com                        *
 *                                                                            *
 * Description: This file contains the README for Branch Monitoring counters  *
 *              interfacing library                                           *
 *                                                                            *
 *                                                                            *
 * Copyright (c) 2018 Intel Corporation                                       *
 *  Permission is granted to copy, distribute and/or modify this document     *
 *  under the terms of the GNU Free Documentation License, Version 1.3        *
 *  or any later version published by the Free Software Foundation;           *
 *  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.*
 *  A copy of the license is included in the section entitled "License".      *
 *                                                                            *
 ******************************************************************************/

Table Of Contents       ..................................... [TOC]

Introduction            ..................................... [INTRO-1]
Dependencies            ..................................... [DEPEN-2]
Building                ..................................... [BUILD-3]
Using the Library       ..................................... [USING-4]
User provided inputs    ..................................... [INPUT-5]
License                 ..................................... [LICEN-6]



[INTRO-1] Introduction
--------------------------------------------------------------------------------
This document describes the libbm library implemented as an interface to the
Branch Monitoring kernel driver.

The Branch Monitoring driver monitors a given task for a possible ROP(Return
Oriented Programming) attack. The user can set a threshold, window size and a
maximum of 2 events (per task/per cpu). Once the threshold is reached, an
interrupt is generated in the driver in which we write a sample and then a user
polls on it, and read it to let the user know if an exploit may have occured.
The user can then take appropriate action. Since 'perf' (a binary tool included
in the Linux Kernel source) is mainly used to 'count' different events, the perf
command line tool cannot be used to monitor branch monitoring events. libbm
closes this gap and provides APIs for interfacing with the Branch monitoring
driver.

[DEPEN-2] Dependencies
--------------------------------------------------------------------------------
libbm depends only on having a modern Linux Kernel installed.

libbm is currently compatible with Linux Kernel version 2.6.32+.

Do this on your system [uname -a]:

     test@test:/tmp$ uname -a
     Linux test 2.6.32-25-generic #45-Ubuntu SMP Sat Oct 16 19:48:22 UTC 2010  \
     i686 GNU/Linux

Which tells us that the kernel we have installed is 2.6.32-25-generic.

[BUILD-3] Building
--------------------------------------------------------------------------------
Building libbm a snap because there are no dependencies!

Then just run ./configure and make as:

     cd libbm
     ./bootstrap.sh
     ./configure
     make
     sudo make install

[USING-4] Using the Library
--------------------------------------------------------------------------------
Using the library is fairly simple.  Obtain a handle into the library using the
'libbm_initialize' function.  This handle may be used in future library calls.
'libbm_enablecounter' and 'libbm_disablecounter' are used to enable and
disable individual counters as desired. 'libbm_close' -- use this function to
just shutdown.

If the pid value is -1, then the library will use the system call 'getpid' to
obtain the process id of the current running process of execution. When 'cpu'
is set to -1, it causes the libbm counters to count across all cpu's for a given
process id. If cpu is set to >=0, then libbm counters count across all tasks
scheduled on that cpu.

Example using some of the functions in an example: libbm_example.c

To compile the previous program the proper flags must be passed to 'gcc':

     export LD_LIBRARY_PATH=/usr/local/lib
     gcc libbm_example.c -o test -L/usr/local/lib -lbm

[INPUT-5] User provided inputs
--------------------------------------------------------------------------------
This library provides a simple interface to allow the user to specify the
following user inputs to the underlying perf driver:

Per-task inputs:
1. LBR freeze:
   Possible values are 0 or 1. When enabled(1), an LBR freeze is observed
   on threshold trip

2. Guest Disable:
   Possible values are 0 or 1. When set to ‘1’, branch
   monitoring feature is disabled when operating at VMX non-root operation.

3. Window size:
   Possible values range from 0 to 1023. This represents the number of
   instructions to be executed before the event counters are reset.

4. Window count select:
   Possible values are:
   0 = instructions retired
   1 = branches retired
   2 = returned instructions retired
   3 = indirect branch instructions retired

5. Count and mode:
   Possible values are 0 or 1. When set to ‘1’, the overall event triggering
   condition is true only if all enabled counter’s threshold conditions are
   true. When ‘0’, the threshold tripping condition is true if either enabled
   counter’s threshold is true. If a counter is not enabled, then it does not
   factor into the AND’ing logic

Per-event inputs:
6. Threshold:
   Values from 1 to 127 is supported. This sets the tipping points. After
   'threshold' number of event hits, an ROP event trigeering condition is
   generated.

7. Mispredict counting behaviour:
   Possible values are:
   0 = mispredict events are counted in a window
   1 = mispredict events are counted based on a consecutive occurrence.

8. Event type:
   Configures the type of event to be counted:
   0-number of returns
   1-call-return imbalance
   2-number of return mispredicts
   3-number of branch mispredicts
   4-number of indirect branch mispredicts
   5-number of far branches

Each task can have a maximum of 2 branch monitoring events configured at any
given time.

[LICEN-6] License
--------------------------------------------------------------------------------
libbm is licensed under the GPLv2 because it includes GPLv2 licensed code from
the perf tool and perf counters subsystem included in the Linux Kernel source
tree.  You may find a copy of this license in the file 'gpl-2.0.txt'.  In
addition, all source code contains a notice at the top with license details.

What this means to you: if you release applications or libraries linking with or
using code from libbm, either statically or dynamically, your applications or
libraries must also be released under the terms of the GPLv2.  Source code must
be made available and contain the proper copyright notices as described in the
GPLv2.

See this official Free Software Foundation FAQ question as reference:

     If a library is released under the GPL (not the LGPL), does that mean
     that any program which uses it has to be under the GPL?
          
          Yes, because the program as it is actually run includes the
          library.

All documentation for libbm is licensed under the GFDLv1.3 which is included
in the file 'fdl-1.3.txt'.