# freescale/libimxvpuapi architecture

> Architecture diagram of the GitHub repository freescale/libimxvpuapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freescale/libimxvpuapi
- Repository: https://github.com/freescale/libimxvpuapi

## Overview

##### Project type and purpose
- This is a C-language frontend library (“libimxvpuapi2”) that abstracts the hardware video codec (VPU) on various Freescale/NXP i.MX SoCs (i.MX6, i.MX8M series).
- It exposes a uniform decoder/encoder API, hides platform‐specific quirks, and relies on lower-level kernel drivers and helper libraries.

##### File structure
- Top‐level:
- debian/ – packaging metadata for Debian
- example/ – standalone C programs demonstrating decode/encode usage
- imxvpuapi2/ – core library source and headers
- waf & wscript – meta-build system scripts (configuration, compile, install)
- libimxvpuapi2.pc.in – pkg-config template
- imxvpuapi2/ directory:
- imxvpuapi2.c/.h – public API entry points, platform dispatch
- imxvpuapi2_priv.c/.h – shared internals (error handling, logging, common routines)
- imxvpuapi2_<platform>_*.c/.h – per-SoC implementations (e.g., imx6 CODA, imx8m Hantro decoder/encoder variants, JPEG)
- example/ directory: utility code (y4m_io.c/h, h264_utils.c/h) and example apps (decode, encode, JPEG)
- Build & packaging: waf scripts define configuration options (–imx-platform), generate the .pc file, install headers & libs. Debian folder contains rules for building cross-arch packages.

##### README for additional insights
- The README describes supported platforms, platform driver dependencies (imx-vpu, imx-vpu-hantro, imx-vpu-hantro-vc) and device nodes (/dev/mxc_hantro, etc.).
- It mentions dependency on libimxdmabuffer for DMA buffer allocation.
- It documents configuration via waf (CC, CFLAGS, LDFLAGS, PKG_CONFIG_PATH, IMX_PLATFORM, SYSROOT).
- Examples read/write raw frames (YUV4MPEG2) and encode/decode H.264 streams.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Packaging"
        WAF["Waf & wscript"]:::build
        PC["pkg-config template"]:::build
        DEB["Debian packaging (debian/)"]:::build
    end

    subgraph "Example Applications"
        DE["decode-example.c"]:::example
        EN["encode-example.c"]:::example
        JD["jpeg-dec-example.c"]:::example
        JE["jpeg-enc-example.c"]:::example
        Y4M["y4m_io.c"]:::example
        H264["h264_utils.c"]:::example
    end

    subgraph "Public API Layer"
        API_C["imxvpuapi2.c"]:::api
        API_H["imxvpuapi2.h"]:::api
    end

    subgraph "Core Internals"
        PRIV_C["imxvpuapi2_priv.c"]:::core
        PRIV_H["imxvpuapi2_priv.h"]:::core
    end

    subgraph "Platform Backends"
        CODA["i.MX6 CODA Backend"]:::backend
        HANTRO_DEC["i.MX8M Hantro Decoder"]:::backend
        DUMMY_ENC["i.MX8M Dummy Encoder"]:::backend
        H1_ENC["i.MX8M H1 Encoder"]:::backend
        VC8000_ENC["i.MX8M VC8000E Encoder"]:::backend
        JPEG["JPEG Encoder/Decoder"]:::backend
    end

    subgraph "External Dependencies"
        DMABUF["libimxdmabuffer"]:::external
        KDRV["Kernel Drivers"]:::external
    end

    HW["VPU Hardware"]:::hardware

    DE -->|"uses"| API_C
    EN -->|"uses"| API_C
    JD -->|"uses"| API_C
    JE -->|"uses"| API_C
    Y4M -->|"I/O utils"| DE
    H264 -->|"codec utils"| DE

    API_C -->|"dispatch"| PRIV_C
    PRIV_C -->|"invokes"| CODA
    PRIV_C -->|"invokes"| HANTRO_DEC
    PRIV_C -->|"invokes"| DUMMY_ENC
    PRIV_C -->|"invokes"| H1_ENC
    PRIV_C -->|"invokes"| VC8000_ENC
    PRIV_C -->|"invokes"| JPEG

    CODA -->|"alloc"| DMABUF
    HANTRO_DEC -->|"alloc"| DMABUF
    DUMMY_ENC -->|"alloc"| DMABUF
    H1_ENC -->|"alloc"| DMABUF
    VC8000_ENC -->|"alloc"| DMABUF
    JPEG -->|"alloc"| DMABUF

    CODA -->|"ioctl"| KDRV
    HANTRO_DEC -->|"ioctl"| KDRV
    DUMMY_ENC -->|"ioctl"| KDRV
    H1_ENC -->|"ioctl"| KDRV
    VC8000_ENC -->|"ioctl"| KDRV
    JPEG -->|"ioctl"| KDRV

    KDRV -->|"controls"| HW

    WAF -->|"configure"| API_C
    WAF -->|"configure"| CODA
    WAF -->|"configure"| HANTRO_DEC
    WAF -->|"configure"| DUMMY_ENC
    WAF -->|"configure"| H1_ENC
    WAF -->|"configure"| VC8000_ENC
    WAF -->|"configure"| JPEG
    WAF -->|"install"| PC

    click API_C "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2.c"
    click API_H "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2.h"
    click PRIV_C "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_priv.c"
    click PRIV_H "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_priv.h"
    click CODA "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_imx6_coda.c"
    click HANTRO_DEC "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_imx8m_hantro_decoder.c"
    click DUMMY_ENC "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_imx8m_hantro_dummy_encoder.c"
    click H1_ENC "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_imx8m_hantro_h1_encoder.c"
    click VC8000_ENC "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_imx8m_hantro_vc8000_encoder.c"
    click JPEG "https://github.com/freescale/libimxvpuapi/blob/master/imxvpuapi2/imxvpuapi2_jpeg.c"
    click DE "https://github.com/freescale/libimxvpuapi/blob/master/example/decode-example.c"
    click EN "https://github.com/freescale/libimxvpuapi/blob/master/example/encode-example.c"
    click JD "https://github.com/freescale/libimxvpuapi/blob/master/example/jpeg-dec-example.c"
    click JE "https://github.com/freescale/libimxvpuapi/blob/master/example/jpeg-enc-example.c"
    click Y4M "https://github.com/freescale/libimxvpuapi/blob/master/example/y4m_io.c"
    click H264 "https://github.com/freescale/libimxvpuapi/blob/master/example/h264_utils.c"
    click WAF "https://github.com/freescale/libimxvpuapi/tree/master/waf"
    click PC "https://github.com/freescale/libimxvpuapi/blob/master/libimxvpuapi2.pc.in"
    click DEB "https://github.com/freescale/libimxvpuapi/tree/master/debian/"

    classDef api fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef hardware fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef example fill:#cce5ff,stroke:#004085,color:#004085;
    classDef build fill:#f8d7da,stroke:#721c24,color:#721c24;
```
