PFPSim Debugger ( pfpdb )

The official debugger provided as a part of the PFPSim Framework for packet level debugging in PFPSim Models linked against the PFPSim Library.

Installation:

Prerequisites

To install pfpdb, you must have:

Any of the officially supported Python versions (2.7, 3.3, 3.4, 3.5)
Either pip or setuptools.

Using the PFPSim GUI Installer

The PFPSim GUI installer can install pfpdb as well as (optionally) the rest of the PFPSim framework and toolchain. This is our recommended install method.

Manually

Download the latest release package from here

Using `pip`:

To install simply run pip install pfpdb*.whl

Using `easy_install`:

If you absolutely must:

easy_install pfpdb*.tar.gz

but you really shouldn't. Here's why you should use pip instead. At this point we assume you are aware of the pitfalls of python eggs and are doing this out of sheer absolute necessity 😦. Shoot us an email why you are using easy_install

Installing from source:

Obtain a copy of the source from this repo or our release page and run:

python setup.py install

Dependencies

Dependencies are automatically installed when using any of the previous methods, but for the curious, they are the following:

Protobuf
- Note for Python 3+ users: The official Protobuf pypi is still not fully compatible with python3 if you have issues please install the following version as:
- pip3 install protobuf==3.0.0b2
- nnpy - Python Bindings for Nanomsg
Tabulate

Usage:

The simplest invocation of the debugger is:

pfpdb <path-to-executable> --args "Arguments to the executable"

Full invocation:

pfpdb [-h] [-v] [--debug] <path-to-executable> --args "ARGS"

Arguments

-v The specified executable is ran launched as a child process whose std::out output piped to the debugger, to view this within the debugger specify the -v flag when launching the debugger
--args "String of Arguments" --args passes what ever is specified to it as a string to arguments to the executable specified when it is launched as a child process by the debugger.
-a This flag searches the current process list for a current running process that matches the specified executable and attaches to it. Please see the attaching to a running simulation section before using the flag.

User Manual

Please see the pfpdb manual for debugger commands.

Developing:

To work on the pfpdb codebase, the first step is obviously to clone this repository. A high level overview of the structure of the code is as follows.

├── dist                          - Release binaries are stored here.
├── LICENSE
├── MANIFEST.in                   - Setuptools Manifest file for packaging.
├── pfpdb
│   ├── __init__.py
│   ├── __main__.py               - main function invoked from shell command pfpdb.
│   ├── pfpdb.py                  - The main debugger source
│   ├── PFPSimDebugger_pb2.py     - Python file generated by the Protobuf compiler from .proto file for protobuf messages.
│   └── PFPSimDebugger.proto      - Protobuf messages.
├── pfpdb-manual.md
├── README.md
└── setup.py                      - Setuptools packaging script.

Download and extract an archive or git clone https://github.com/pfpsim/pfpdb.git and cd into the directory.

Simply run:

$ python setup.py develop

pfpdb is now available as a system wide shell command, $ command -v pfpgen can be used to confirm this.

Changes made to codebase should be immediately reflected.

Flexible Invocation in develop mode:

In addition to it being available as a shell command the debugger can be run right from the source directory as a python module.

$ python -m pfpdb [-h] [-v] [--debug] --args "ARGS" exe_path

App Note: Making changes to the .proto file requires you to run python setup.py develop or the protobuf compiler protoc manually as protoc, "-I=./", "--python_out=./" to regenerate PFPSimDebugger_pb2.py`

Contributing

To contribute your changes back to pfpdb please fork this repository on Github and send us a pull request!

Attaching to a Running Simulation:

Launch the simulation as
- ./executable argumentstoexecutable -d
- NOTE: Don't forget the -d flag this is very important
Launch the debugger as
- pfpdb executable --args "arguments to executable" -v -a

Why attach to a running simulation?

pfpdb is a packet level debugger, but you may want to debug your code in a C++ debugger like gdb when things go awry. This allows you to see the state of your simulation and debug your code in gdb in parallel.

Terminal 1:

$ gdb ./executable
...
...
...
(gdb) r argumentstoexecutable -d
(gdb) .... debug your code execution...

Terminal 2:

$ pfpdb executable --args "arguments to executable" -v -a
Launching executable as child process...
...
...
...
(PFPSimDebug)  ... debug your code behaviour ...

Built With

A whole lot of Coffee and Ice tea.

Support

If you need help using pfpdb, please send us an email at pfpsim.help@gmail.com - we'd be happy to hear from you!

If you think you've found a bug, or would like to request a new feature, please open an issue using github - we're always trying to improve pfpdb!

License

This project is licensed under the GPLv2 - see the LICENSE file for details

Authors

Samar Abdi
Eric Tremblay
Umair Aftab
Gordon Bailey
Faras Dewal
Shafigh Parsazad

Bochra Boughzala

pfpsim/pfpdb