pynq.drivers package — Python productivity for Zynq (Pynq) v1.0

# pynq.drivers package

## Submodules

## pynq.drivers.audio module

class `pynq.drivers.audio.``Audio`

  Bases: `object`

  Class to interact with audio controller.

  Each audio sample is a 32-bit integer. The audio controller supports only mono mode, and uses pulse density modulation (PDM).

  `base_addr`

    int – The base address of the audio controller (e.g. 0x43C0000).

  `length`

    int – Length of audio controller address space (e.g. 0x10000).

  `buffer`

    numpy.ndarray – The numpy array to store the audio.

  `sample_rate`

    int – Sample rate of the current buffer content.

  `sample_len`

    int – Sample length of the current buffer content.

  `bypass_start`()

    Stream audio controller input directly to output.

    Parameters: | None –
    Returns: |
    Return type: | None

  `bypass_stop`()

    Stop streaming input to output directly.

    Parameters: | None –
    Returns: |
    Return type: | None

  `info`(file)

    Prints information about pdm files.

    The information includes name, channels, samples, frames, etc.

    Note

    The file will be searched in the specified path, or in the working directory in case the path does not exist.

    Parameters: | file (string) – File name, with a default extension of pdm.
    Returns: |
    Return type: | None

  `load`(file)

    Loads file into internal audio buffer.

    The recorded file is of format *.pdm.

    Note

    The file will be searched in the specified path, or in the working directory in case the path does not exist.

    Parameters: | file (string) – File name, with a default extension of pdm.
    Returns: |
    Return type: | None

  `play`()

    Play audio buffer via audio jack.

    Parameters: | None –
    Returns: |
    Return type: | None

  `record`(seconds)

    Record data from audio controller to audio buffer.

    The sample rate per word is 192000Hz.

    Parameters: | seconds (float) – The number of seconds to be recorded.
    Returns: |
    Return type: | None

  `save`(file)

    Save audio buffer content to a file.

    The recorded file is of format *.pdm.

    Note

    The saved file will be put into the specified path, or in the working directory in case the path does not exist.

    Parameters: | file (string) – File name, with a default extension of pdm.
    Returns: |
    Return type: | None

## pynq.drivers.dma module

class `pynq.drivers.dma.``DMA`(address, direction=1, attr_dict=None)

  Bases: `object`

  Python class which controls DMA.

  This is a generic DMA class that can be used to access main memory.

  The DMA direction can be:

  (0)`DMA_TO_DEV` : DMA sends data to PL.

  (1)`DMA_FROM_DEV` : DMA receives data from PL.

  (3)`DMA_BIDIRECTIONAL` : DMA can send/receive data from PL.

  `buf`

    cffi.FFI.CData – A pointer to physically contiguous buffer.

  `bufLength`

    int – Length of internal buffer in bytes.

  `phyAddress`

    int – Physical address of the DMA device.

  `DMAengine`

    cdata ‘XAxiDma *’ – DMA engine instance defined in C. Not to be directly modified.

  `DMAinstance`

    cdata ‘XAxiDma_Config *’ – DMA configuration instance struct. Not to be directly modified.

  `direction`

    int – The direction indicating whether DMA sends/receives data from PL.

  `Configuration`

    dict – Current DMAinstance configuration values.

  `configure`(attr_dict=None)

    Reconfigure and Reinitialize the DMA IP.

    Uses a user provided dict to reinitialize the DMA. This method also frees the internal buffer associated with current object.

    The keys in attr_dict should exactly match the ones used in default config. All the keys are not required. The default configuration is defined in dma.DefaultConfig dict. Users can reinitialize the DMA with new configuratiuon after creating the object.

    Parameters: | attr_dict (dict) – A dictionary specifying DMA configuration values.
    Returns: |
    Return type: | None

  `create_buf`(num_bytes, cacheable=0)

    Allocate physically contiguous memory buffer.

    Allocates/Reallocates buffer needed for DMA operations.

    Possible values for parameter cacheable are:

    1: the memory buffer is cacheable.

    0: the memory buffer is non-cacheable.

    Note

    This buffer is allocated inside the kernel space using xlnk driver. The maximum allocatable memory is defined at kernel build time using the CMA memory parameters. For Pynq-Z1 kernel, it is specified as 128MB.

    Parameters:

    - num_bytes (int) – Length of the allocated array in bytes.
    - cacheable (int) – Indicating whether or not the memory buffer is cacheable

    Returns: |
    Return type: | None

  `free_buf`()

    Free the memory buffer associated with this object.

    Use this to free a previously allocated memory buffer. This is specially useful for reallocations.

    Parameters: | None –
    Returns: |
    Return type: | None

  `get_buf`(width=32)

    Get a CFFI pointer to object’s internal buffer.

    This can be accessed like a regular array in python. The width can be either 32 or 64.

    Parameters: | width (int) – The data width in the buffer.
    Returns: | An CFFI object which can be accessed similar to arrays in C.
    Return type: | cffi.FFI.CData

  `transfer`(num_bytes, direction=1)

    Transfer data using DMA (Non-blocking).

    Used to initiate transfer of data between a physically contiguous buffer and PL. The buffer should be allocated using create_buf before this call.

    The num_bytes should be less than buffer size and DMA_TRANSFER_LIMIT_BYTES.

    Possible values for direction are:

    (0)`DMA_TO_DEV` : DMA sends data to PL.

    (1)`DMA_FROM_DEV` : DMA receives data from PL.

    Parameters:

    - num_bytes (int) – Number of bytes to transfer.
    - direction (int) – Direction in which DMA transfers data.

    Returns: |
    Return type: | None

  `wait`(wait_timeout=10)

    Block till DMA is busy or a timeout occurs.

    Default value of timeout is 10 seconds.

    Parameters: | wait_timeout (int) – Time to wait in seconds before timing out wait operation.
    Returns: |
    Return type: | None

class `pynq.drivers.dma.``timeout`(seconds=1, error_message='Timeout')

  Bases: `object`

  Internal timeout functions.

  This class is only used internally.

  `handle_timeout`(signum, frame)

## pynq.drivers.trace_buffer module

class `pynq.drivers.trace_buffer.``Trace_Buffer`(if_id, protocol, trace=None, data=None, samplerate=500000)

  Bases: `object`

  Class for the trace buffer, leveraging the sigrok libraries.

  This trace buffer class gets the traces from DMA and processes it using the sigrok commands.

  Note

  The sigrok-cli library has to be installed before using this class.

  `protocol`

    str – The protocol the sigrok decoder are using.

  `trace_csv`

    str – The absolute path of the trace file *.csv.

  `trace_sr`

    str – The absolute path of the trace file *.sr, translated from *.csv.

  `trace_pd`

    str – The absolute path of the decoded file by sigrok.

  `probes`

    list – The list of probes used for the trace.

  `dma`

    DMA – The DMA object associated with the trace buffer.

  `ctrl`

    MMIO – The MMIO class used to control the DMA.

  `samplerate`

    int – The samplerate of the traces.

  `data`

    cffi.FFI.CData – The pointer to the starting address of the trace data.

  `csv2sr`()

    Translate the *.csv file to *.sr file.

    The translated *.sr files can be directly used in PulseView to show the waveform.

    Note

    This method also modifies the input *.csv file (the comment header, usually 3 lines, will be removed).

    Parameters: | None –
    Returns: |
    Return type: | None

  `decode`(decoded_file, options='')

    Decode and record the trace based on the protocol specified.

    The decoded_file contains the name of the output file.

    The option specifies additional options to be passed to sigrok-cli. For example, users can use option=’:wordsize=9:cpol=1:cpha=0’ to add these options for the SPI decoder.

    The decoder will also ignore the pin collected but not required for decoding.

    Note

    The output file will have *.pd extension.

    Note

    The decoded file will be put into the specified path, or in the working directory in case the path does not exist.

    Parameters:

    - decoded_file (str) – The name of the file recording the outputs.
    - options (str) – Additional options to be passed to sigrok-cli.

    Returns: |
    Return type: | None

  `display`(start_pos, stop_pos)

    Draw digital waveforms in ipython notebook.

    It utilises the wavedrom java script library, documentation for which can be found here: https://code.google.com/p/wavedrom/.

    Note

    Only use this method in Jupyter notebook.

    Note

    WaveDrom.js and WaveDromSkin.js are required under the subdirectory js.

    Example of the data format to draw waveform:

        >>> data = {'signal': [

    {‘name’: ‘clk’, ‘wave’: ‘p.....|...’},

    {‘name’: ‘dat’, ‘wave’: ‘x.345x|=.x’, ‘data’: [‘D’,’A’,’T’,’A’]},

    {‘name’: ‘req’, ‘wave’: ‘0.1..0|1.0’},

    {},

    {‘name’: ‘ack’, ‘wave’: ‘1.....|01.’}

    ]}

    Parameters:

    - start_pos (int) – The starting sample number (relative to the trace).
    - stop_pos (int) – The stopping sample number (relative to the trace).

    Returns: |
    Return type: | None

  `parse`(parsed, start=0, stop=524288, mask=18446744073709551615, tri_sel=[], tri_0=[], tri_1=[])

    Parse the input data and generate a *.csv file.

    This method can be used along with the DMA. The input data is assumed to be 64-bit. The generated *.csv file can be then used as the trace file.

    To extract certain bits from the 64-bit data, use the parameter mask.

    Note

    The probe pins selected by mask does not include any tristate probe.

    To specify a set of tristate probe pins, e.g., users can set tri_sel = [0x0000000000000004], tri_0 = [0x0000000000000010], and tri_1 = [0x0000000000000100]. In this example, the 3rd probe from the LSB is the selection probe; the 5th probe is selected if selection probe is 0, otherwise the 9th probe is selected. There can be multiple sets of tristate probe pins.

    Note

    The parsed file will be put into the specified path, or in the working directory in case the path does not exist.

    Parameters:

    - parsed (str) – The file name of the parsed output.
    - start (int) – The first 64-bit sample of the trace.
    - stop (int) – The last 64-bit sample of the trace.
    - mask (int) – A 64-bit mask to be applied to the 64-bit samples.
    - tri_sel (list) – The list of tristate selection probe pins.
    - tri_0 (list) – The list of probe pins selected when the selection probe is 0.
    - tri_1 (list) – The list probe pins selected when the selection probe is 1.

    Returns: |
    Return type: | None

  `set_metadata`(probes)

    Set metadata for the trace.

    A *.sr file directly generated from *.csv will not have any metadata. This method helps to set the sample rate, probe names, etc.

    The list probes depends on the protocol. For instance, the I2C protocol requires a list of [‘SDA’,’SCL’].

    Parameters: | probes (list) – A list of probe names.
    Returns: |
    Return type: | None

  `show`()

    Show information about the specified protocol.

    Parameters: | None –
    Returns: |
    Return type: | None

  `sr2csv`()

    Translate the *.sr file to *.csv file.

    The translated *.csv files can be used for interactive plotting. It is human readable.

    Note

    This method also removes the redundant header that is generated by sigrok.

    Parameters: | None –
    Returns: |
    Return type: | None

  `start`(timeout=10)

    Start the DMA to capture the traces.

    Parameters: | timeout (int) – The time in number of milliseconds to wait for DMA to be idle.
    Returns: |
    Return type: | None

  `stop`()

    Stop the DMA after capture is done.

    Note

    There is an internal timeout mechanism in the DMA class.

    Parameters: | None –
    Returns: |
    Return type: | None

## pynq.drivers.video module

class `pynq.drivers.video.``Frame`(width, height, frame=None)

  Bases: `object`

  This class exposes the bytearray of the video frame buffer.

  Note

  The maximum frame width is 1920, while the maximum frame height is 1080.

  `frame`

    bytearray – The bytearray of the video frame buffer.

  `width`

    int – The width of a frame.

  `height`

    int – The height of a frame.

  `save_as_jpeg`(path)

    Save a video frame to a JPEG image.

    Note

    The JPEG filename must be included in the path.

    Parameters: | path (str) – The path where the JPEG will be saved.
    Returns: |
    Return type: | None

  static `save_raw_as_jpeg`(path, frame_raw, width, height)

    Save a video frame (in bytearray) to a JPEG image.

    Note

    This is a static method of the class.

    Parameters:

    - path (str) – The path where the JPEG will be saved.
    - frame_raw (bytearray) – The video frame to be saved.
    - width (int) – The width of the frame.
    - height (int) – The height of the frame.

    Returns: |
    Return type: | None

class `pynq.drivers.video.``HDMI`(direction, video_mode=4, init_timeout=10, frame_list=None)

  Bases: `object`

  Class for an HDMI controller.

  The frame buffer in an HDMI object can be shared among different objects. e.g., HDMI in and HDMI out objects can use the same frame buffer.

  Note

  HDMI supports direction ‘in’ and ‘out’.

  Examples

      >>> hdmi = HDMI('in')

      >>> hdmi = HDMI('out')

  `direction`

    str – Can be ‘in’ for HDMI IN or ‘out’ for HDMI OUT.

  `frame_list`

    _framebuffer – A frame buffer storing at most 3 frames.

  `VMODE_1024x768` = 2
  `VMODE_1280x1024` = 3
  `VMODE_1920x1080` = 4
  `VMODE_640x480` = 0
  `VMODE_800x600` = 1
  `frame` = None

    Wraps the raw version using the Frame object.

    Use frame([index]) to read the frame more easily.

    Parameters: | index (int, optional) – Index of the frames, from 0 to 2.
    Returns: | A Frame object with accessible pixels.
    Return type: | Frame

  `frame_addr` = None

    Get the current frame address.

    Parameters: | i (int, optional) – Index of the current frame buffer.
    Returns: | Address of the frame, thus current frame buffer.
    Return type: | int

  `frame_height` = None

    Get the current frame height.

    Parameters: | None –
    Returns: | The height of the frame.
    Return type: | int

  `frame_index` = None

    Get the frame index.

    Use frame_index([new_frame_index]) to access the frame index. If new_frame_index is not specified, get the current frame index. If new_frame_index is specified, set the current frame to the new index.

    Parameters: | new_frame_index (int, optional) – Index of the frames, from 0 to 2.
    Returns: | The index of the active frame.
    Return type: | int

  `frame_index_next` = None

    Change the frame index to the next one.

    Parameters: | None –
    Returns: | The index of the active frame.
    Return type: | int

  `frame_phyaddr` = None

    Get the current physical frame address.

    Parameters: | i (int, optional) – Index of the current frame buffer.
    Returns: | Physical address of the frame, thus current frame buffer.
    Return type: | int

  `frame_raw` = None

    Get the frame as a bytearray.

    User may use frame([index]) to access the frame, which may introduce some overhead in rare cases. The method frame_raw([i]) is faster, but the parameter i has to be calculated manually.

    Parameters: | i (int, optional) – A location in the bytearray.
    Returns: | The frame in its raw bytearray form.
    Return type: | bytearray

  `frame_width` = None

    Get the current frame width.

    Parameters: | None –
    Returns: | The width of the frame.
    Return type: | int

  `mode` = None

    Change the resolution of the display.

    Users can use mode(new_mode) to change the resolution. Specifically, with new_mode to be:

    0 : '640x480@60Hz‘

    1 : '800x600@60Hz‘

    2 : '1280x720@60Hz‘

    3 : '1280x1024@60Hz‘

    4 : '1920x1080@60Hz‘

    If new_mode is not specified, return the current mode.

    Parameters: | new_mode (int) – A mode index from 0 to 4.
    Returns: | The resolution of the display.
    Return type: | str
    Raises: | `ValueError` – If new_mode is out of range.

  `start`(timeout=20)

    Start the video controller.

    Parameters: | None –
    Returns: |
    Return type: | None

  `state` = None

    Get the state of the device as an integer value.

    Parameters: | None –
    Returns: | The state 0 (DISCONNECTED), or 1 (STREAMING), or 2 (PAUSED).
    Return type: | int

  `stop` = None

    Stop the video controller.

    Parameters: | None –
    Returns: |
    Return type: | None

## pynq.drivers.xlnk module

`pynq.drivers.xlnk.``sig_handler`(signum, frame)

class `pynq.drivers.xlnk.``xlnk`

  Bases: `object`

  Class to enable CMA memory management.

  The CMA state maintained by this class is local to the application except for the CMA Memory Available attribute which is global across all the applications.

  `bufmap`

    dict – Mapping of allocated memory to the buffer sizes in bytes.

  `cma_alloc`(length, cacheable=0, data_type='void')

    Allocate physically contiguous memory buffer.

    Allocates a new buffer and adds it to bufmap.

    Possible values for parameter cacheable are:

    1: the memory buffer is cacheable.

    0: the memory buffer is non-cacheable.

    Examples

    memmanager = xlnk.xlnk()

    # Allocate 10 void * memory locations.

    m1 = memmanager.cma_alloc(10)

    # Allocate 10 float * memory locations.

    m2 = memmanager.cma_alloc(10, data_type = “float”)

    Notes

    1. Total size of buffer is automatically calculated as size = length * sizeof(data_type)

    2. This buffer is allocated inside the kernel space using xlnk driver. The maximum allocatable memory is defined at kernel build time using the CMA memory parameters. For Pynq-Z1 kernel, it is specified as 128MB.

    The unit of length depends upon the data_type argument.

    Parameters:

    - length (int) – Length of the allocated buffer. Default unit is bytes.
    - cacheable (int) – Indicating whether or not the memory buffer is cacheable.
    - data_type (str) – CData type of the allocated buffer. Should be a valid C-Type.

    Returns: | An CFFI object which can be accessed similar to arrays.
    Return type: | cffi.FFI.CData

  static `cma_cast`(data, data_type='void')

    Cast underlying buffer to a specific C-Type.

    Input buffer should be a valid object which was allocated through cma_alloc or a CFFI pointer to a memory buffer. Handy for changing void buffers to user defined buffers.

    Parameters:

    - data (cffi.FFI.CData) – A valid buffer pointer allocated via cma_alloc.
    - data_type (str) – New data type of the underlying buffer.

    Returns: | Pointer to buffer with specified data type.
    Return type: | cffi.FFI.CData

  `cma_free`(buf)

    Free a previously allocated buffer.

    Input buffer should be a valid object which was allocated through cma_alloc or a CFFI pointer to a memory buffer.

    Parameters: | buf (cffi.FFI.CData) – A valid buffer pointer allocated via cma_alloc.
    Returns: |
    Return type: | None

  `cma_get_buffer`(buf, length)

    Get a buffer object.

    Used to get an object which supports python buffer interface. The return value thus, can be cast to objects like bytearray, memoryview etc.

    Parameters:

    - buf (cffi.FFI.CData) – A valid buffer object which was allocated through cma_alloc.
    - len (int) – Length of buffer in Bytes.

    Returns: | A CFFI object which supports buffer interface.
    Return type: | cffi.FFI.CData

  static `cma_memcopy`(dest, src, nbytes)

    High speed memcopy between buffers.

    Used to perform a byte level copy of data from source buffer to the destination buffer.

    Parameters:

    - dest (cffi.FFI.CData) – Destination buffer object which was allocated through cma_alloc.
    - src (cffi.FFI.CData) – Source buffer object which was allocated through cma_alloc.
    - nbytes (int) – Number of bytes to copy.

    Returns: |
    Return type: | None

  `cma_stats`()

    Get current CMA memory Stats.

    CMA Memory Available : Systemwide CMA memory availability.

    CMA Memory Usage : CMA memory used by current object.

    Buffer Count : Buffers allocated by current object.

    Parameters: | None –
    Returns: | Dictionary of current stats.
    Return type: | dict

  `xlnk_reset`()

    Systemwide Xlnk Reset.

    Notes

    This method resets all the CMA buffers allocated across the system.

    Parameters: | None –
    Returns: |
    Return type: | None

## Module contents