Merge pull request iovisor#180 from iovisor/bblanco_dev

Update README.md and INSTALL.md, specfile dependencies

INSTALL.md

@@ -4,25 +4,25 @@ Install a 4.2+ kernel from http://kernel.ubuntu.com/~kernel-ppa/mainline,
 for example:
 
 ```bash
-VER=4.2.0-040200rc5
-REL=201508030228
-PREFIX=http://kernel.ubuntu.com/~kernel-ppa/mainline/v4.2-rc5-unstable
+VER=4.2.0-040200
+REL=201508301530
+PREFIX=http://kernel.ubuntu.com/~kernel-ppa/mainline/v4.2-unstable
 wget ${PREFIX}/linux-headers-${VER}-generic_${VER}.${REL}_amd64.deb
 wget ${PREFIX}/linux-headers-${VER}_${VER}.${REL}_all.deb
 wget ${PREFIX}/linux-image-${VER}-generic_${VER}.${REL}_amd64.deb
 sudo dpkg -i linux-*${VER}.${REL}*.deb
 # reboot
 ```
 
-Tagged binary packages are built for Ubuntu Trusty (14.04) and hosted at
+Tagged bcc binary packages are built for Ubuntu Trusty (14.04) and hosted at
 http://52.8.15.63/apt/.
 
 To install:
 ```bash
 sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys D4284CDD
 echo "deb http://52.8.15.63/apt trusty main" | sudo tee /etc/apt/sources.list.d/iovisor.list
 sudo apt-get update
-sudo apt-get install libbcc
+sudo apt-get install libbcc libbcc-examples python-bcc
 ```
 
 Test it:
@@ -36,24 +36,25 @@ cd pyroute2; sudo make install
 sudo python /usr/share/bcc/examples/simple_tc.py
 ```
 
-# Fedora - Docker edition
-
-The build dependencies are captured in a [Dockerfile](Dockerfile.fedora), the
-output of which is a .rpm for easy installation. This version takes longer since
-LLVM needs to be compiled from source.
-
-* Start with a recent Fedora install (tested with F22)
-* Install a [>= 4.2 kernel](http://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug/x86_64/)
-  with headers
-* Reboot
-* Install [docker](https://docs.docker.com/installation/fedora/)
-* Run the Dockerfile for Fedora - results in an installable .rpm
-  * `git clone https://github.com/iovisor/bcc; cd bcc`
-  * `docker build -t bcc -f Dockerfile.fedora .`
-  * `docker run --rm -v /tmp:/mnt bcc sh -c "cp /root/bcc/build/*.rpm /mnt"`
-  * `sudo rpm -ivh /tmp/libbcc*.rpm`
-* Run the example
-  * `sudo python /usr/share/bcc/examples/hello_world.py`
+# Fedora - Binary
+
+Install a 4.2+ kernel from
+http://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug, for example:
+
+```bash
+sudo wget http://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug/fedora-rawhide-kernel-nodebug.repo -O /etc/yum.repos.d/fedora-rawhide-kernel-nodebug.repo
+sudo dnf install -y kernel-core-4.2.0-1.fc24.x86_64 kernel-4.2.0-1.fc24.x86_64 kernel-devel-4.2.0-1.fc24.x86_64 kernel-modules-4.2.0-1.fc24.x86_64 kernel-headers-4.2.0-1.fc24.x86_64
+# reboot
+```
+
+Tagged bcc binary packages are built for Fedora 22 and hosted at
+http://52.8.15.63/yum/.
+
+To install:
+```bash
+sudo wget http://52.8.15.63/yum/main/f22/iovisor.repo -O /etc/yum.repos.d/iovisor.repo
+sudo dnf install -y libbcc libbcc-examples python-bcc
+```
 
 # Ubuntu - From source
 
@@ -79,3 +80,19 @@ To build the toolchain from source, one needs:
   * `make`
   * `sudo make install`
 
+# Fedora - From source
+
+* Install build dependencies
+  * `sudo dnf install -y bison cmake ethtool flex git iperf libstdc++-static python-netaddr python-pip gcc gcc-c++ make zlib-devel`
+  * `sudo dnf install -y http://pkgs.repoforge.org/netperf/netperf-2.6.0-1.el6.rf.x86_64.rpm`
+  * `sudo pip install pyroute2`
+* Install binary clang
+  * `wget http://llvm.org/releases/3.7.0/clang+llvm-3.7.0-x86_64-fedora22.tar.xz`
+  * `sudo tar xf clang+llvm-3.7.0-x86_64-fedora22.tar.xz -C /usr/local --strip 1`
+* Install and compile BCC
+  * `git clone https://github.com/iovisor/bcc.git`
+  * `mkdir bcc/build; cd bcc/build`
+  * [optional] `export CC=/usr/local/bin/clang CXX=/usr/local/bin/clang++`
+  * `cmake .. -DCMAKE_INSTALL_PREFIX=/usr`
+  * `make`
+  * `sudo make install`

README.md

@@ -41,6 +41,7 @@ The features of this toolkit include:
       tc actions, and kprobes
 * Bindings for Python
 * Examples for socket filters, tc classifiers, and kprobes
+* Self-contained tools for tracing a running system
 
 In the future, more bindings besides python will likely be supported. Feel free
 to add support for the language of your choice and send a pull request!
@@ -77,19 +78,14 @@ For this example, we will call the program every time `fork()` is called by a
 userspace process. Underneath the hood, fork translates to the `clone` syscall,
 so we will attach our program to the kernel symbol `sys_clone`.
 ```python
-fn = b.load_func("hello", BPF.KPROBE)
-BPF.attach_kprobe(fn, "sys_clone")
+b.attach_kprobe(event="sys_clone", fn_name="hello")
 ```
 
 The python process will then print the trace printk circular buffer until ctrl-c
 is pressed. The BPF program is removed from the kernel when the userspace
 process that loaded it closes the fd (or exits).
 ```python
-from subprocess import call
-try:
-    call(["cat", "/sys/kernel/debug/tracing/trace_pipe"])
-except KeyboardInterrupt:
-    pass
+b.trace_print()
 ```
 
 Output:
@@ -98,6 +94,9 @@ bcc/examples$ sudo python hello_world.py
           python-7282  [002] d...  3757.488508: : Hello, World!
 ```
 
+For an explanation of the meaning of the printed fields, see the trace_pipe
+section of the [kernel ftrace doc](https://www.kernel.org/doc/Documentation/trace/ftrace.txt).
+
 [Source code listing](examples/hello_world.py)
 
 ### Networking
@@ -138,6 +137,9 @@ struct key_t {
 };
 // map_type, key_type, leaf_type, table_name, num_entry
 BPF_TABLE("hash", struct key_t, u64, stats, 1024);
+// attach to finish_task_switch in kernel/sched/core.c, which has the following
+// prototype:
+//   struct rq *finish_task_switch(struct task_struct *prev)
 int count_sched(struct pt_regs *ctx, struct task_struct *prev) {
   struct key_t key = {};
   u64 zero = 0, *val;
@@ -153,10 +155,11 @@ int count_sched(struct pt_regs *ctx, struct task_struct *prev) {
 [Source code listing](examples/task_switch.c)
 
 The userspace component loads the file shown above, and attaches it to the
-`finish_task_switch` kernel function (which takes one `struct task_struct *`
-argument). The `get_table` API returns an object that gives dict-style access
-to the stats BPF map. The python program could use that handle to modify the
-kernel table as well.
+`finish_task_switch` kernel function.
+The [] operator of the BPF object gives access to each BPF_TABLE in the
+program, allowing pass-through access to the values residing in the kernel. Use
+the object as you would any other python dict object: read, update, and deletes
+are all allowed.
 ```python
 from bcc import BPF
 from time import sleep
@@ -172,25 +175,6 @@ for k, v in b["stats"].items():
 ```
 [Source code listing](examples/task_switch.py)
 
-## Requirements
-
-To get started using this toolchain in binary format, one needs:
-* Linux kernel 4.1 or newer, with these flags enabled:
-  * `CONFIG_BPF=y`
-  * `CONFIG_BPF_SYSCALL=y`
-  * `CONFIG_NET_CLS_BPF=m` [optional, for tc filters]
-  * `CONFIG_NET_ACT_BPF=m` [optional, for tc actions]
-  * `CONFIG_BPF_JIT=y`
-  * `CONFIG_HAVE_BPF_JIT=y`
-  * `CONFIG_BPF_EVENTS=y` [optional, for kprobes]
-* Headers for the above kernel
-* gcc, make, python
-* python-pyroute2 (for some networking features only)
-
 ## Getting started
 
-As of this writing, binary packages for the above requirements are available
-in unstable formats. Both Ubuntu and Fedora have 4.2-rcX builds with the above
-flags defaulted to on. LLVM provides 3.7 Ubuntu packages (but not Fedora yet).
-
 See [INSTALL.md](INSTALL.md) for installation steps on your platform.

SPECS/bcc.el6.spec

@@ -88,6 +88,7 @@ make install/strip DESTDIR=%{buildroot}
 
 %package -n libbcc
 Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: make, gcc
 %description -n libbcc
 Shared Library for BPF Compiler Collection (BCC)
 

SPECS/bcc.el6.spec.in

@@ -88,6 +88,7 @@ make install/strip DESTDIR=%{buildroot}
 
 %package -n libbcc
 Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: make, gcc
 %description -n libbcc
 Shared Library for BPF Compiler Collection (BCC)
 

SPECS/bcc.el7.spec

@@ -57,6 +57,7 @@ make install/strip DESTDIR=%{buildroot}
 
 %package -n libbcc
 Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: make, gcc
 %description -n libbcc
 Shared Library for BPF Compiler Collection (BCC)
 

SPECS/bcc.el7.spec.in

@@ -57,6 +57,7 @@ make install/strip DESTDIR=%{buildroot}
 
 %package -n libbcc
 Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: make, gcc
 %description -n libbcc
 Shared Library for BPF Compiler Collection (BCC)
 

SPECS/bcc.f22.spec

@@ -57,6 +57,7 @@ make install/strip DESTDIR=%{buildroot}
 
 %package -n libbcc
 Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: make, gcc
 %description -n libbcc
 Shared Library for BPF Compiler Collection (BCC)
 

SPECS/bcc.f22.spec.in

@@ -57,6 +57,7 @@ make install/strip DESTDIR=%{buildroot}
 
 %package -n libbcc
 Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: make, gcc
 %description -n libbcc
 Shared Library for BPF Compiler Collection (BCC)
 

SPECS/bcc.spec

@@ -0,0 +1,66 @@
+%define debug_package %{nil}
+
+Name:           bcc
+Version:        0.1.6
+Release:        1%{?dist}
+Summary:        BPF Compiler Collection (BCC)
+
+Group:          Development/Languages
+License:        ASL 2.0
+URL:            https://github.com/iovisor/bcc
+Source0:        bcc.tar.gz
+
+BuildArch:      x86_64
+BuildRequires:  bison, cmake >= 2.8.7, flex, gcc, gcc-c++, python2-devel
+
+%description
+Python bindings for BPF Compiler Collection (BCC). Control a BPF program from
+userspace.
+
+
+%prep
+%setup -n bcc
+
+%build
+
+mkdir build
+pushd build
+cmake .. -DREVISION=%{version} -DCMAKE_INSTALL_PREFIX=/usr
+make -j`grep -c ^process /proc/cpuinfo`
+popd
+
+%install
+pushd build
+make install/strip DESTDIR=%{buildroot}
+
+%changelog
+* Fri Jul 03 2015 Brenden Blanco <[email protected]> - 0.1.1-2
+- Initial RPM Release
+
+%package -n libbcc
+Summary: Shared Library for BPF Compiler Collection (BCC)
+Requires: gcc, make
+%description -n libbcc
+Shared Library for BPF Compiler Collection (BCC)
+
+%package -n libbcc-examples
+Summary: Examples for BPF Compiler Collection (BCC)
+%description -n libbcc-examples
+Examples for BPF Compiler Collection (BCC)
+
+%package -n python-bcc
+Summary: Python bindings for BPF Compiler Collection (BCC)
+%description -n python-bcc
+Python bindings for BPF Compiler Collection (BCC)
+
+%files -n python-bcc
+%{python_sitelib}/bcc*
+%exclude %{python_sitelib}/*.egg-info
+
+%files -n libbcc
+/usr/lib64/*
+/usr/share/bcc/include/*
+/usr/include/bcc/*
+
+%files -n libbcc-examples
+/usr/share/bcc/examples/*

scripts/build-rpm.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -x
+set -e
+
+TMP=$(mktemp -d /tmp/rpmbuild.XXXXXX)
+
+function cleanup() {
+  [[ -d $TMP ]] && rm -rf $TMP
+}
+trap cleanup EXIT
+
+mkdir $TMP/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
+git archive HEAD --prefix=bcc/ --format=tar.gz -o $TMP/SOURCES/bcc.tar.gz
+cp SPECS/bcc.spec $TMP/SPECS/
+pushd $TMP
+rpmbuild --define "_topdir `pwd`" -ba SPECS/bcc.spec
+popd
+
+cp $TMP/RPMS/*/*.rpm .
+cp $TMP/SRPMS/*.rpm .