Signed-off-by: Yuji Ishikawa yuji2.ishikawa@toshiba.co.jp --- v1 -> v2: - newly added documents --- Documentation/driver-api/visconti/common.rst | 115 ++++++ Documentation/driver-api/visconti/dnn.rst | 394 +++++++++++++++++++ 2 files changed, 509 insertions(+) create mode 100644 Documentation/driver-api/visconti/common.rst create mode 100644 Documentation/driver-api/visconti/dnn.rst
diff --git a/Documentation/driver-api/visconti/common.rst b/Documentation/driver-api/visconti/common.rst new file mode 100644 index 000000000..cc2d3f6cd --- /dev/null +++ b/Documentation/driver-api/visconti/common.rst @@ -0,0 +1,115 @@ +========================================== +Common interfaces for Visconti IPA Drivers +========================================== + +file operation +============== + +IPA driver expose thair function to userspace with device files. + +* The device file has specific name, such as /dev/dnn0 +* device file provides some operations + + - open / close + - two ioctls operations to control IPA + - poll to wait for the finish of IPA + +IOCTLs +====== + +All IPA drivers have following two IOCTL requests. +See individual documents of IPA drivers for detail. + +.. c:macro:: IOC_IPA_START + +starts IPA processing. + +.. c:macro:: IOC_IPA_GET_STATUS + +get the status of IPA driver + +IPA Addresses +============= + +IPA drivers assume that the buffers for IPA HW processing are DMA-BUF +which are phisically contiguous memory block allocated with DMA-BUF heaps. +The heap area is defined with a reserved-memory element in device tree description. +See Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt for further information. + +Two structures are used to describe DMA-BUF instances. + +* :c:type:`drv_ipa_buffer_info` +* :c:type:`drv_ipa_addr` + +Note that allocation size of DMA-BUF instances should be power of two. +This is mainly because IOMMUs have very limited number of entries for translation. + + +drv_ipa_buffer_info +------------------- + +Information about the buffer allocated with DMA-BUF heaps. +Applications specify the array of drv_ipa_buffer_info to the driver. + +drv_ipa_addr +------------ + +Application specify the region to be processed with two information; index for the array of drv_ipa_buffer_info and offset. + +.. c:macro:: IPA_INVALID_ADDR + +When a buffer is an optional parameter for an API, application can use :c:macro:`IPA_INVALID_ADDR` instead of NULL. + +For example: + +.. code-block:: c + + struct drv_ipa_addr null_addr = IPA_INVALID_ADDR; + +Code exampe +----------- + +.. code-block:: c + + /* hogehoge */ + /* hogehoge */ + +Structures +========== + +.. kernel-doc:: drivers/soc/visconti/uapi/ipa.h + +Further description of addressing +================================= + +DRAM addressing space +--------------------- + +Visconti5 (TMPV770x) SoCs have 2 DDR controllers. +Each space for a controller is mapped in 36bit address space as follows: + +* DDR0: 0x0_8000_0000 - 0x0_FFFF_FFFF +* DDR1: 0x8_8000_0000 - 0x8_FFFF_FFFF + +IPAs have dedicated IOMMUs (visconti ioatu) which translate 32bit IOVA to 36bit physical address. +Note that address registers of IPA core hardware only accept 32bit values. +When IOMMUs are absent (by removing their description from device tree), DDR1 address must not be used for IPA. + +Coherent access among CPUs / IPAs +--------------------------------- + +Bus master of IPAs has two connections; direct access to DRAM and cache-coherent connection with CPU clusters. +The bit 34 of 64bit address is used to distinguish direct access or coherent acccess. + +* DDR0 (direct): 0x0_8000_0000 - 0x0_FFFF_FFFF +* DDR0 (coherent): 0x4_8000_0000 - 0x4_FFFF_FFFF +* DDR1 (direct): 0x8_8000_0000 - 0x8_FFFF_FFFF +* DDR1 (coherent): 0xC_8000_0000 - 0xC_FFFF_FFFF + +If the whole system should run coherent mode, make following changes in device tree description: + +* set coherent address for all memory and reserved-memory elements +* set dma_coherent property to all IPA elements + +It is strongly recommended not to use both direct and coherent address at the same time. + diff --git a/Documentation/driver-api/visconti/dnn.rst b/Documentation/driver-api/visconti/dnn.rst new file mode 100644 index 000000000..1abdd6c7c --- /dev/null +++ b/Documentation/driver-api/visconti/dnn.rst @@ -0,0 +1,394 @@ +======================= +Visconti DNN IPA driver +======================= + +Hardware overview +================= + +Visconti DNN IPA is a proprietary CNN/DCNN accelerator developed by Toshiba. +This IPA integrates large scaled parallel MAC units and dedicated function units to accelerate +inference operation of well known neural network layers. It also has dedicated DMA unit to make accesses to DRAM. +Visconti5 SoC has 2 instances of DNN accelerator hardware. + +WORDS: + +* IPA: Image Processing Accelerator +* CNN: Convolutional Neural Network +* DCNN: Deep Convolutional Neural Network + +Software architecture +===================== + +The operation of Visconti DNN IPA depends on some software components including this kernel driver. +Some extra components are provided by Toshiba Electronic Device & Storage Company (at Jul 2022). + +* libdrvutil: userspace utility to build a descriptor for a NN inference operation. +* compiler: offline tool to generate configuration binaries from caffe/onnx compatible CNN models. + +The Visconti DNN IPA driver receives a configuration binary and an input vector then configures hardware registers. +Register values suitable for each run is held in a descriptor data structure generated by libdrvutil. + +The userland and the kernel driver use DMA-BUF to allocate/handle (phisically contiguous) memory blocks. + +Public user interface of Visconti DNN IPA driver is exposed as following device files. + +* DNN0: /dev/dnn0 +* DNN1: /dev/dnn1 + +IOCTLs +====== + +IOC_IPA_START +------------- + +.. c:function:: int ioctl( int fd, IOC_IPA_START, drv_dnn_descriptor_t *argp ) + :name: IOC_IPA_START_DNN + +Description +~~~~~~~~~~~ + +This ioctl call starts the DNN processing with specified descriptor. +:c:type:`drv_dnn_descriptor_t` should be set by :ref:`util_dnn` + +poll(2) will return when the DNN processing is completed. +DNN HW does not stop IPA processing by execution error. +DNN driver will report POLLERR with completed event, if the execution error occurs. +Applications can check the error information by calling :c:func:`ioctl(IOC_IPA_GET_STATUS) <IOC_IPA_GET_STATUS_DNN>`. + +Return value +~~~~~~~~~~~~ + +On success, 0 is returned. +On error, -1 is returned and the ``errno`` is set appropriately. + +Errors +~~~~~~ + +* EBUSY: Driver is busy. +* EFAULT: + + - The given descriptor is not accessible from kernel space. + - ``src_list`` is not accessible from kernel space. + - ``dst_list`` is not accessible from kernel space. + +* EINVAL: + + - The given descriptor is not configured by :ref:`drv_DNN_config_descript_finalize`. + - Ion heap fd passed in :ref:`drv_DNN_config_descript_init` (buffer) is invalid. + - ``configuration_binary_addr.offset`` is greater than or equal to size of Ion heap pointed by ``configuration_binary_addr.buffer_index``. + - ``temporary_addr.offset`` is greater than or equal to size of Ion heap pointed by ``temporary_addr.buffer_index``. + - ``src_list[0 ~ n-1]`` is :c:macro:`IPA_INVALID_ADDR`. + - ``src_list[0 ~ n-1].buffer_index`` is equal to or greater than ``buffer_num`` of :ref:`drv_DNN_config_descript_init`. + - ``src_list[0 ~ n-1].offset`` is greater than or equal to size of Ion heap pointed by ``src_list[0 ~ n-1].buffer_index``. + - ``dst_list[0 ~ n-1]`` is :c:macro:`IPA_INVALID_ADDR`. + - ``dst_list[0 ~ n-1].buffer_index`` is equal to or greater than ``buffer_num`` of :ref:`drv_DNN_config_descript_init`. + - ``dst_list[0 ~ n-1].offset`` is greater than or equal to size of Ion heap pointed by ``dst_list[0 ~ n-1].buffer_index``. + +IOC_IPA_GET_STATUS +------------------ + +.. c:function:: int ioctl( int fd, IOC_IPA_GET_STATUS, drv_dnn_status_t *argp ) + :name: IOC_IPA_GET_STATUS_DNN + +Description +~~~~~~~~~~~ + +| This ioctl call asks the DNN driver to get the state of the DNN HW. +| See :c:type:`drv_dnn_status_t` for details. + +Error +~~~~~ + +* EFAULT: The given status structure is not accessible from kernel space. + +.. _util_dnn: + + +Userspace utility functions +=========================== + +.. _drv_DNN_config_descript_init: + +drv_DNN_config_descript_init +---------------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + int32_t drv_DNN_config_descript_init( + drv_dnn_descriptor_t *desc, + struct drv_ipa_buffer_info *buffer, + int32_t buffer_num + ); + +Parameters +~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + + * - :c:type:`drv_dnn_descriptor_t` *desc + - Pointer to the DNN descriptor structure. + * - :c:type:`struct drv_ipa_buffer_info <drv_ipa_buffer_info>` *buffer + - Array of Ion heaps for DNN processing. + * - int32_t buffer_num + - Number of buffer. [1, 15] + +Description +~~~~~~~~~~~ + +Initializes the :c:type:`drv_dnn_descriptor_t` structure with value 0 and sets Array of Ion heaps. + +Return value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + + * - :c:macro:`DRV_OK` + - Operation completes successfully. + * - :c:macro:`DRV_ERROR_PARAMETER` + - * ``desc`` is NULL. + * ``buffer`` is NULL. + * ``buffer_num`` is out of range. + * ``direction`` member in ``buffer`` is invalid. + +.. _drv_DNN_config_exec_configuration: + +drv_DNN_config_exec_configuration +--------------------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + int32_t drv_DNN_config_exec_configuration( + drv_dnn_descriptor_t *desc, + const void *configuration_binary, + struct drv_ipa_addr configuration_binary_addr, + struct drv_ipa_addr *src_list, + struct drv_ipa_addr *dst_list, + int32_t list_num, + struct drv_ipa_addr temporary_addr, + int32_t temporary_size + ); + +Parameters +~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + + * - :c:type:`drv_dnn_descriptor_t` *desc + - Pointer to the DNN descriptor structure. + * - const void *configuration_binary + - Userland address of the configuration binary. + * - :c:type:`struct drv_ipa_addr <drv_ipa_addr>` *configuration_binary_addr + - IPA address of the configuration binary. Should be aligned to 512 byte. + * - :c:type:`struct drv_ipa_addr <drv_ipa_addr>` *src_list + - Userland address for the list of IPA address to input data. + * - :c:type:`struct drv_ipa_addr <drv_ipa_addr>` *dst_list + - Userland address for the list of IPA address to output data. + * - int32_t list_num + - Number of list. [1, 1024] + * - :c:type:`struct drv_ipa_addr <drv_ipa_addr>` *temporary_addr + - IPA address of the temporary memory. Should be aligned to 4 byte. + * - int32_t temporary_size + - Size of the temporary memory. + +Description +~~~~~~~~~~~ + +Configures :c:type:`drv_dnn_descriptor_t` structure with execute configuration parameters. + +* ``desc`` should be initialized by :ref:`drv_DNN_config_descript_init` before the descriptor configuration. +* If configuration binary provides temporary buffer setting, temporary_addr should not be :c:macro:`IPA_INVALID_ADDR` and should be aligned to 4 byte. +* If configuration binary does not provide temporary buffer setting, applications can specify :c:macro:`IPA_INVALID_ADDR` for temporary_addr. +* Configuration binary for ``configuration_binary`` parameter should be created by DNN toolchain. + + +Return value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + + * - :c:macro:`DRV_OK` + - Operation completes successfully. + * - :c:macro:`DRV_ERROR_PARAMETER` + - * ``desc`` is NULL. + * ``configuration_binary`` is NULL. + * ``configuration_binary_addr`` is :c:macro:`IPA_INVALID_ADDR`. + * ``configuration_binary_addr.buffer_index`` is equal to or greater than ``buffer_num`` of :ref:`drv_DNN_config_descript_init`. + * ``configuration_binary_addr.offset`` is not aligned to 512 byte. + * ``src_list`` is NULL. + * ``dst_list`` is NULL. + * ``list_num`` is out of range. + * ``temporary_addr`` is :c:macro:`IPA_INVALID_ADDR` when configuration binary requires more than 0 byte for temporary memory. + * ``temporary_addr.offset`` is not aligned to 4 byte when it is valid. + * ``temporary_addr.buffer_index`` is equal to or greater than ``buffer_num`` of :ref:`drv_DNN_config_descript_init` when it is valid. + * - :c:macro:`DRV_DNN_ERROR_INVALID_CONFIGURATION_BINARY` + - In Configuration binary, + + * base address mode N is except 0:unused, 1:list, 2:fixed. + * base address purpose N is except 1:input, 2:output, 3:weight/bias, 4:temporary. + * base address mode is not list when purpose is input or output + * base address mode is not fixed when purpose is temporary or weight/bias + * - :c:macro:`DRV_DNN_ERROR_TEMPORARY_MEMORY_SIZE` + - ``temporary_size`` is smaller than the size which is required by configuration binary. + +.. _drv_DNN_config_descript_finalize: + +drv_DNN_config_descript_finalize +-------------------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + int32_t drv_DNN_config_descript_finalize( + drv_dnn_descriptor_t *desc + ); + +Parameters +~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + + * - :c:type:`drv_dnn_descriptor_t` *desc + - | Pointer to the DNN descriptor structure + + +Description +~~~~~~~~~~~ + +Checks if DNN driver descriptor configuration is complete before starting DNN HW. + +``desc`` should be initialized by :ref:`drv_DNN_config_descript_init` before the descriptor configuration. + +Return value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + + * - :c:macro:`DRV_OK` + - Operation completes successfully. + * - :c:macro:`DRV_ERROR_PARAMETER` + - ``desc`` is NULL. + * - :c:macro:`DRV_ERROR_IPA_CONFIG_INCOMPLETE` + - :ref:`drv_DNN_config_exec_configuration` is not called after :ref:`drv_DNN_config_descript_init`. + +Structures +========== + +.. kernel-doc:: drivers/soc/visconti/uapi/dnn.h + +Code example +============ + +``src_list`` and ``dst_list`` parameter for :ref:`drv_DNN_config_exec_configuration` is the array of :c:type:`drv_ipa_addr`. + +.. code-block:: c + + #include <fcntl.h> + #include <poll.h> + #include <stdbool.h> + #include <stdint.h> + #include <sys/ioctl.h> + #include <sys/mman.h> + #include <sys/stat.h> + #include <sys/types.h> + #include <unistd.h> + + #include <linux/dma-heap.h> + + #include "drv_ipa.h" + #include "drv_dnn_util.h" + + #define HEAP_ID (2) + #define CONFIG_SIZE <size of configuration binary> + #define INPUT_SIZE <input buffer size> + #define OUTPUT_SIZE <output buffer size> + #define TEMP_SIZE <temporary size in configuration binary> + #define LIST_NUM (2) + + #define NUM_OF_BUFS (4) + + void dnn_sample(void) + { + int ret; + int32_t drv_ret; + int32_t fd_heap, fd_dnn; + struct pollfd fds[1]; + int32_t timeout; + unsigned char *src, *config; + struct dma_heap_allocation_data alloc_src={0}, alloc_dst={0}, alloc_temp={0}, alloc_config={0}; + drv_dnn_descriptor_t desc; + + /* Open DMA-BUF heaps device for heap allocation */ + fd_heap = open("/dev/dma_heap/linux,cma", O_RDWR); + + /* Open DNN device for processing */ + fd_dnn = open("/dev/dnn0", O_RDWR); + + /* Input buffer */ + alloc_src.len = INPUT_SIZE; /* Size should be power of 2 */ + alloc_src.fd_flags = O_RDWR | O_CLOEXEC; + ret = ioctl(fd_heap, DMA_HEAP_IOCTL_ALLOC, &alloc_src); + + src = mmap(0, alloc_src.len, PROT_READ | PROT_WRITE, MAP_SHARED, alloc_src.fd, 0); + + alloc_config.len = CONFIG_SIZE; /* Size should be power of 2 */ + alloc_config.fd_flags = O_RDWR | O_CLOEXEC; + ret = ioctl(fd_ion, DMA_HEAP_IOCTL_ALLOC, &alloc_config); + + config = mmap(NULL, alloc_config.len, PROT_READ | PROT_WRITE, MAP_SHARED, alloc_config.fd, 0); + + alloc_temp.len = TEMP_SIZE; /* Size should be power of 2 */ + alloc_temp.fd_flags = ION_FLAG_CACHED; + ret = ioctl(fd_ion, DMA_HEAP_IOCTL_ALLOC, &alloc_temp); + + /* Output buffer */ + alloc_dst.len = OUTPUT_SIZE; /* Size should be power of 2 */ + alloc_dst.flags = O_RDWR | O_CLOEXEC; + ret = ioctl(fd_ion, DMA_HEAP_IOCTL_ALLOC, &alloc_dst); + + /* Create buffer info data for descriptor */ + struct drv_ipa_buffer_info bufinfo[NUM_OF_BUFS] + = {{.fd = alloc_config.fd, .direction = DRV_IPA_DIR_TO_DEVICE}, + {.fd = alloc_src.fd, .direction = DRV_IPA_DIR_TO_DEVICE}, + {.fd = alloc_temp.fd, .direction = DRV_IPA_DIR_FROM_DEVICE}, + {.fd = alloc_dst.fd, .direction = DRV_IPA_DIR_FROM_DEVICE}}; + + struct drv_ipa_addr config_addr = {.buffer_index = 0, .offset = 0}; + struct drv_ipa_addr src_list_addr[LIST_NUM] = {{.buffer_index = 1, .offset = 0}, {.buffer_index = 1, .offset = 0x300}}; + struct drv_ipa_addr temp_addr = {.buffer_index = 2, .offset = 0}; + struct drv_ipa_addr dst_list_addr[LIST_NUM] = {{.buffer_index = 3, .offset = 0}, {.buffer_index = 3, .offset = 0x300}}; + + /* Configure descriptor */ + drv_ret = drv_DNN_config_descript_init(&desc, bufinfo, NUM_OF_BUFS); + + drv_ret = drv_DNN_config_exec_configuration(&desc, config, config_addr, src_list_addr, dst_list_addr, LIST_NUM, temp_addr, + TEMP_SIZE); + + drv_ret = drv_DNN_config_descript_finalize(&desc); + + /* Start DNN */ + ret = ioctl(fd_dnn, IOC_IPA_START, &desc); + + /* Wait DNN */ + fds[0].fd = fd_dnn; + fds[0].events = POLLIN; + timeout = 1000; // 1sec + + ret = poll(fds, 1, timeout); + + close(fd_ion); + close(fd_dnn); + }