========================= PYTHON BINDINGS FOR NETMAP ==========================

The extra/python directory contains a C extension module that makes
it possible to use netmap from the Python (2.7 versions) programming
language.


(1) **************************** How to compile it ****************************

    cd extra/python
    make


(2) ************ How to (compile and) install it in your system ***************

    cd extra/python
    make install


(3) How to use it with python

        >>> import netmap
        >>> # your code here
        >>> ...


(4) ************************ Python classes for netmap ************************

        The netmap extension module exports three Python classes that represent
        the netmap memory layout:
            (4.1) netmap.NetmapInterface - represents a "netmap_if" struct
            (4.2) netmap.NetmapRing - represents a "netmap_ring" struct
            (4.3) netmap.NetmapSlot - represents a "netmap_slot" struct

        The struct fields are **directly** read/write accessible (e.g. you are
        accessing the real netmap memory) through the class members.

        You can issue

            >>> help(netmap.NetmapRing)

        or

            >>> help(r)  # "r" is a reference to a netmap.NetmapRing instance

        to see the documentation (members and methods) of the specified class.

        The other two classes available in the netmap extension module
        (netmap.Netmap and netmap.NetmapDesc) are intended to create, manage
        and contain the netmap memory layout representation.
        Each instance of such classes is intended to manage a network
        interface.

            (4.5) netmap.Netmap - Apart from containing the netmap memory
                    layout (once the NIOCREGIF is done), it is basically a
                    wrapper for a "nmreq" struct, and can therefore be used
                    to access the whole netmap API.
                    Its constructor doesn't take any arguments, and allows the
                    user to use the ioctl netmap interface (NIOCREGIF,
                    NIOCGINFO, ...).

                    Example:
                    >>> import netmap
                    >>> n=netmap.Netmap()
                    >>> n.open()  # open the netmap device
                    >>> n.if_name = 'eth0'
                    >>> n.register()  # registers all the hw rings of "eth0"
                    >>> # access n.interface, n.transmit_rings, n.receive_rings
                    >>> n.close()

                    See help(netmap.Netmap) for reference.

            (4.6) netmap.NetmapDesc - This class is even simpler than
                    netmap.Netmap(), in that you don't have to separately
                    create the object, open the device and register, but you
                    can do these three operation with the constructor only.
                    Apart from this, you can use the nm_open() extended
                    interface names to specify what kind of registration you
                    desire (in fact the C backend for this class is nm_open()).

                    Example:
                    >>> import netmap
                    >>> d=netmap.NetmapDesc('netmap:enp1s0f1*')
                    >>> # access d.interface, d.transmit_rings, d.receive_rings



(5) ****************************** More examples ******************************

    You can find some examples in extra/python:

        (5.1) pktman.py - A configurable packet generator/receiver. Run

                    $ python pktman.py -h

                to see the available options.

        (5.2) tx.py - An minimal packet generator using the lower level
                      Python netmap bindings, it is able to transmit
                      more than 20 Mpps.