.. index::
    Nanos6 API

.. _nanos6_api:

Nanos6 FPGA Architecture API
:::::::::::::::::::::::::::::

The following sections list and summarize the Nanos++ FPGA Architecture API.
The documentation is for the version 10.

Memory Management
=================

nanos6_fpga_malloc
------------------

Allocates memory in the FPGA address space and returns a pointer valid for the
FPGA tasks. The returned pointer cannot be dereferenced in the host code.

Arguments:
 - **size**: Size in bytes to allocate.
 - **fpga_addr**: Pointer to the FPGA address space as a 64-bit integer.

Return value:
 - NANOS6_FPGA_SUCCESS on success, NANOS6_FPGA_ERROR on error.

.. code:: c

    typedef enum {
        NANOS6_FPGA_SUCCESS,
        NANOS6_FPGA_ERROR
    } nanos6_fpga_stat_t;

    nanos6_fpga_stat_t nanos6_fpga_malloc(uint64_t size, uint64_t* fpga_addr);

nanos_fpga_free
---------------

.. code:: c

    nanos6_fpga_stat_t nanos6_fpga_free(uint64_t fpga_addr);

nanos_fpga_memcpy
-----------------

.. code:: c

    typedef enum {
        NANOS6_FPGA_DEV_TO_HOST,
        NANOS6_FPGA_HOST_TO_DEV
    } nanos6_fpga_copy_t;

    nanos6_fpga_stat_t nanos6_fpga_memcpy(
        void* usr_ptr,
        uint64_t fpga_addr,
        uint64_t size,
        nanos6_fpga_copy_t copy_type);

Data copies
===========

These Nanos6 API only can be called inside an FPGA task.
They alloy copies to be performed through a single port
that can be wider than the data type being copied.

If any of the data copy API calls are used, the :ref:`llvm_fpga_options_port_width` option is mandatory.

Data accessed through this functions, has to be **aligned to the port width**.
Otherwise this will result in undefined behaviour.

Also, data should to be **multiple of the port width**.
If this cannot be guaranteed, :ref:`llvm_fpga_options_check_limits` option is needed
so that no out of bounds data is accessed.
Otherwise this will result in undefined behaviour.

nanos6_fpga_memcpy_wideport_in
-----------------------------

.. code:: c

    nanos6_fpga_stat_t nanos6_fpga_memcpy_wideport_in(void* dst, const unsigned long long int addr, const unsigned int num_elems);

Arguments:

- ``dst``: Pointer to the destination (local) data. It can be any data type.
- ``addr``: FPGA memory address space where the data is stored.
- ``num_elems``: Number of elements of the array type to be copied.

nanos6_fpga_memcpy_wideport_out
-------------------------------

.. code:: c

    nanos6_fpga_stat_t nanos6_fpga_memcpy_wideport_out(void* dst, const unsigned long long int addr, const unsigned int num_elems);

Arguments:

- ``dst``: Pointer to the source (local) data. It can be any data type.
- ``addr``: FPGA memory address space where the data is written.
- ``num_elems``: Number of elements of the array type to be copied.