.. image:: https://travis-ci.org/benreynwar/axilent.svg?branch=master
               :target: https://travis-ci.org/benreynwar/axilent

axilent
=======

axilent provides python tools for describing a sequence of Axi4Lite command
in python.

A python test can be written describing the sequence of commands to be sent
and the expected responses.  This test can then be run against both a
simulation of the design and against the implemented design running on an
FPGA.

axilent is structured so that tests can be run both against both interactive
simulations and simulations where inputs cannot depend on outputs such as
file-based testbenchs.


Handlers
--------

Currently there is `handler` for working with file-based testbenchs
generated by `slvcodec <https://github.com/benreynwar/slvcodec>`_ and
for simulations on FPGAs run over JTAG using
`pyvivado <https://github.com/benreynwar/pyvivado>`_.
In the likely event you are using neither of these methods, then you
will have to write you own handler. The handler has a single required
method.

handler.send(command)
    Sends a command to the FPGA, or adds the command to the list of commands that
    will be run in the simulation.

The handler also processes the responses from the simulation or FPGA and updates the
`command.future` values appropriately.  It calls the `command.process_responses` method
to help process the responses.


Commands
--------
A `Command` object represents a simple axi4lite read or write, or a more complex
aggregrate consisting of many read and write commands.

command.get_axi_commands()
    Returns a list of `AxiCommand` objects.  Each `AxiCommand` object is a simple
    axi4lite read or write command to a single address or a range of addresses.

command.process_responses(read_responses, write_responses, resolve_future)
    Processes two lists of `AxiResponse` objects, one is a list of responses to
    write requests and one is a list of responses to read requests.  The two lists
    must begin with the responses to this command, and these entries are removed
    from the lists.
    An (exception, result) tuple is returned by the function.  If `resolve_future`
    is True then the commands future is resolved with the result and exception.

As an example consider an AxiAdder module, which uses an Axi4Lite interface.  We can
write to registers A and B, and when we read from register C the returned result is
the sum of the contents in regsiters A and B.  We can create a `Command` object to
represent using this hardware to add two numbers.

.. code:: python
          
    class AddNumbersCommand(comms.CombinedCommand):
        '''
        A command that writes to the intA and intB registers
        and then reads from the intC register.
        The effect is the add the two inputs.
        '''
    
        def __init__(self, a, b, addresses):
            write_a_command = comms.SetUnsignedCommand(
                address=addresses['intA'], value=a,
                description='Setting A in AddNumbers',
            )
            write_b_command = comms.SetUnsignedCommand(
                address=addresses['intB'], value=b,
                description='Setting B in AddNumbers',
            )
            read_c_command = comms.GetUnsignedCommand(
                address=addresses['intC'],
                description='Getting C from AddNumbers',
            )
            commands = (write_a_command, write_b_command, read_c_command)
            super().__init__(
                description='Add 2 numbers with AddNumber',
                commands=commands)
    
        def process_responses(self, read_responses, write_responses, resolve_future=True):
            '''
            Return the third response (from the final read command)
            Don't return any errors.
            '''
            e, result = super().process_responses(read_responses, write_responses, resolve_future=False)
            intc = result[2]
            if resolve_future:
                self.resolve_future(e, intc)
            return e, intc

    

Comm
----
Typically command objects are hidden from the testing interface by wrapping them
with a Comm object.  Methods on this comm object create `Command` objects, send
them to a handler, and return the command futures.

.. code:: python

    class AxiAdderComm:
        '''
        Class to communicate with the AxiAdder module.
        '''
    
        INTA_ADDRESS = 0
        INTB_ADDRESS = 1
        INTC_ADDRESS = 2
    
        def __init__(self, address_offset, handler):
            '''
            `address_offset` is any addition that is made to the address that is
            consumed during routing.
            `handler` is the object responsible for dispatching the commands.
            '''
            self.handler = handler
            self.address_offset = address_offset
            self.addresses = {
                'intA': address_offset + self.INTA_ADDRESS,
                'intB': address_offset + self.INTB_ADDRESS,
                'intC': address_offset + self.INTC_ADDRESS,
            }
    
        def add_numbers(self, a, b):
            '''
            A complex complex command that write to two registers and
            then reads from another.
            Sets 'a' and 'b' then reads 'c' (should be a+b)
            '''
            command = AddNumbersCommand(a, b, self.addresses)
            self.handler.send(command)
            return command.future

Tests
-----
A possible way to write a test to is define a class with a `prepare` method that
defines the requests to send to the module, and a `check` method that analyzes
the responses.

The `prepare` method uses a `handler` to generate the requests and creates a
number of futures to hold the results of processing the responses.

The responses are then processed by a handler-dependent method and then the
`check` method can be run to check the contents of the resolved futures.

.. code:: python

    class AxiAdderTest(object):
    
        def __init__(self):
            self.expected_intcs = []
            self.intc_futures = []
    
        def prepare(self, handler):
            '''
            Sends a number of 'add_numbers' commands.
            '''
            comm = AxiAdderComm(address_offset=0, handler=handler)
            n_data = 20
            max_int = pow(2, 16)-1
            logger.debug('preparing data')
            for i in range(n_data):
                inta = random.randint(0, max_int)
                intb = random.randint(0, max_int)
                self.expected_intcs.append(inta + intb)
                future = comm.add_numbers(inta, intb)
                self.intc_futures.append(future)
            # Flush the communication for simulations.
            # Ignored in FPGA.
            handler.send(comms.FakeWaitCommand(clock_cycles=10))
    
        def check(self):
            '''
            Check that the output of the commands matches the expected values.
            '''
            output_intcs = [f.result() for f in self.intc_futures]
            assert output_intcs == self.expected_intcs
            print('Success!!!!!!!!!!!!!!!')



Repeatability of Simulations
----------------------------
Although the simulations are repeatable the FPGA-based tests are currently not
repeatable because of the changing number of clock-cycles between when requests
are received.
I would like to fix this by allowing the ability of specify on which clock
cycle at AXI request should be sent (they would be gathered in a delayed in a buffer
on the FPGA until the correct clock cycle).
TODO: Add delaying of requests to allow repeatability.
