simaaisrc
=========

This plugin reads a given file from the file system and puts it into
SiMa memory, so that another SiMa plugins (like ``process2`` or
``process-cvu``) can read it from SiMa memory.

The ``simaaisrc`` plugin functions similarly to the ``filesrc`` and
``multifilesrc`` plugins but offers support for SiMa memory allocation.
It is particularly useful for debugging and developing SiMa pipelines.
By enabling the simulation of input data, the ``simaaisrc`` plugin
allows for isolated testing of other plugins, facilitating more
efficient development and troubleshooting of new pipeline components.

Properties
----------

+-----------------------------------+-----------------------------------+
| Property                          | Description                       |
+===================================+===================================+
| ``location``                      | An absolute path to the file      |
|                                   | which will be used as an input.   |
+-----------------------------------+-----------------------------------+
| ``node-name``                     | The name of the plugin being      |
|                                   | mocked (can be taken from its     |
|                                   | ``config.json``).                 |
+-----------------------------------+-----------------------------------+
| ``blocksize``                     | Size of the input file in bytes.  |
+-----------------------------------+-----------------------------------+
| ``delay``                         | Delay before the buffer is pushed |
|                                   | to the next plugin, in            |
|                                   | milliseconds.                     |
+-----------------------------------+-----------------------------------+
| ``mem-target``                    | Type of SiMa memory used for      |
|                                   | allocation. Possible values are:  |
|                                   | ``0``: Allocating into A65 CPU    |
|                                   | memory; ``1``: Allocating into    |
|                                   | EV74 CVU memory; - ``2`` or       |
|                                   | ``4``: Allocating into MLA memory |
+-----------------------------------+-----------------------------------+
| ``segments``                      | Forces an element to allocate     |
|                                   | memory using the segment memory   |
|                                   | API. See the section below for a  |
|                                   | detailed explanation.             |
+-----------------------------------+-----------------------------------+

Usage
-----

.. code-block:: bash :linenos:

::

   ! gst-launch-1.0 simaaisrc location=/data/test-001.out mem-target=0 .. !

Assuming you have a pipeline that looks like:

::

   input_image -> decoder -> pre-process[EV74] -> process[MLA] -> post-process[EV74] -> nms[A65] -> output

And there is a need to debug NMS plugin because for some reason it does
not provide to you valid output.

For debugging sake it is important to preserve deterministic input, so
developer can check NMS plugin work step by step using GDB or any other
tool.

To do that, we don’t really need the rest of plugins in the pipeline
(like decoder, process-cvu, process2, etc). Instead, we can mock the
input by using ``simaaisrc`` plugin and simplify pipeline to:

::

   simaaisrc -> nms -> fakesink

Let’s see how it will look like in real world:

- First of all, we need to get the output for the previous plugin (in
  our case it could be a ``process-cvu`` plugin that runs post
  processing EV graph). To dump the output of it you need to set
  ``dump: 1`` in ``post-process.json`` config file.

- Once you did that - run your pipeline as usual, without any other
  modifications for few seconds. After that you should be able to see
  ``ev-post-process-XXX.out`` files at ``/tmp`` folder on the board.

- Take one file (for example ``ev-post-process-001.out``) and copy to
  ``/data``. This step is needed, because ``/tmp`` is not a persistent
  storage and after board reboot all data will disappear and you’ll need
  to get the dumps again. \`

- Now you’re ready to start using the ``simaaisrc`` plugin:

  ::

     gst-launch-1.0 gst-plugin-path=/path/plugins/folder simaaisrc location=/data/ev-post-process-001.out node-name="ev-cnet-postproc" blocksize=786432 delay=1000 mem-target=0 ! fakesink

Segment Property
~~~~~~~~~~~~~~~~

The ``segment`` property provides a mechanism to allocate logical parts
of contigous buffer with their own unique names instead of allocating
the entire buffer. This mechanism is extremely useful when the user
wants to debug/troubleshoot the ``processcvu_new`` element. This element
uses a new Dispatcher API, that requires memory segments as an input. In
this scenario, the user can use separate files that correspond to each
segment. Let’s take an example:

OpenPose post-process graph ``pose_postproc`` requires two tensors that
represent HM (Heat Map) and PAF (Partial affinity fields). To do that
the user can run the following GStreamer string:

::

   gst-launch-1.0 simaaisrc segments='hm_tensor=/data/hm_tensor_in,paf_tensor=/data/paf_tensor_in' node-name=simaaiprocessmla0 mem-target=1 delay=30 ! 'application/vnd.output-mla' ! simaaiprocesscvu_new name='simaai_postproc' num-buffers=5 config='/data/mem_segments/config_postproc.json' dump_data=true ! 'application/vnd.openpose-postproc' ! fakesink

The new property ``segments`` takes a string that is a comma-separated
key=value pairs. Key represents a segment name that will be used in
downstream element, and value is the path to the file that represents a
binary data associated with the given segment.

NOTE: User shall use **only one** of these two properties: ``segments``
or ``location``.

Configuration
-------------

This plugin does not need any configuration.