// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
  \page vxworks.html
  \title Qt for VxWorks
  \brief Platform support for VxWorks.
  \keyword VxWorks
  \ingroup supportedplatform

  Contact The Qt Company for more information:
  \l {https://www.qt.io/contact-us/}

  \section1 Qt for VxWorks Licensing

    Qt for VxWorks is available under the Qt for Device Creation Professional
    (DCP) license. For more information, see \l{Qt Pricing}.

  \section1 Supported Architectures and VxWorks Releases

  \list
    \li Qt 6.7 is verified on VxWorks 24.03
    Supported architecture is ARM-v7.
  \endlist

  If you are interested in later Qt releases, please \l {https://www.qt.io/contact-us/}{contact} Qt
  professional services.

  \section1 Requirements for VxWorks

  \section2 Qt Widgets Applications

  \list
  \li POSIX support
  \li C++17 support
  \endlist

  \section2 Qt Quick 2 Applications

  All features which are required for Qt Widgets applications, and in addition the following:

  \list
  \li GPU device (GPUDEV) for OpenGL ES 2.0
  \endlist

  \section1 Supported Modules

  Most essential \l{All Modules}{Qt modules} and some add-on modules are supported.

  \section2 Supported Essential modules

  \table 80%
  \header
      \li Qt Module
      \li Supported Features
      \li Notes
  \row
      \li \l {Qt Core}
      \li
      \li No support for \l{QProcess}. \l{QLocalSocket} and \l{QLocalServer} support only SOCK_SEQPACKET.
  \row
      \li \l {Qt GUI}
      \li
      \li
  \row
      \li \l {Qt Network}
      \li
      \li
  \row
      \li \l {Qt Qml}
      \li
      \li
  \row
      \li \l {Qt Quick}
      \li
      \li
  \row
      \li \l {Qt Quick Controls}
      \li
      \li
  \row
      \li \l {Qt Quick Dialogs}
      \li
      \li
  \row
      \li \l {Qt Quick Layouts}
      \li
      \li
  \row
      \li \l {Qt Quick Test}
      \li
      \li
  \row
      \li \l {Qt Test}
      \li
      \li
  \row
      \li \l {Qt Widgets}
      \li
      \li
  \endtable

  \section2 Supported Add-Ons

  \table 80%
  \header
      \li Qt Add-Ons
      \li Notes
  \row
      \li \l {Qt Concurrent}
      \li
  \row
      \li \l {Qt GRPC}{Qt GRPC/Protobuf}
      \li
  \row
      \li \l {Qt Graphs}
      \li
  \row
      \li \l {Qt Image Formats}
      \li
  \row
      \li \l {Qt Multimedia}
      \li
  \row
      \li \l {Native Interfaces}{Qt Native Interfaces}
      \li
  \row
      \li \l {Qt OpenGL}
      \li
  \row
      \li \l {Qt Quick 3D}
      \li
  \row
      \li \l {Qt Quick Compiler}
      \li
  \row
      \li \l {Qt Quick Effects}
      \li
  \row
      \li \l {Qt SQL}
      \li
  \row
      \li \l {Qt SVG}
      \li
  \row
      \li \l {Qt Virtual Keyboard}
      \li
  \endtable

  \note You can explicitly exclude unsupported or unused modules from the
  build via the -skip <module> option when running the configure tool.

  \section1 Platform Notes

  With the release of Qt 5.0, Qt no longer contains its own window system
  implementation: QWS is no longer a supported platform. For single-process use
  cases, the \l{Qt Platform Abstraction} is a superior solution.

  There is one plugin that is usable on VxWorks: EGLFS. The availability of this
  plugins depends on the configuration of Qt.

  \section1 Configuring for a Specific Device

  Prepare your environment by installing VxWorks SDK and obtaining WindRiver
  license which is needed by installer and for building VxWorks images.
  Search for appropriate installer in
  {https://gallery.windriver.com/portal/products}.

  Building Qt for a given device requires a Qt 6 installation for compilation
  host, a toolchain and a sysroot. Additionally, some devices require vendor
  specific adaptation code for EGL and OpenGL 2.0 support.

  \section2 VxWorks Image Requirements

  Qt for VxWorks requires certain VxWorks image bundles and components to be
  embedded in base software to make Qt compile and work properly. The
  list is by no means complete as it depends on hardware, software and system
  requirements of your project. However, the following table contains those
  that are mandatory for certain functionalities to work. Note also that these
  might change with VxWorks versions.

  \section3 Example VSB configuration for i.MX 6 BSP

  You need to add the following features to VSB for Qt to work properly. For
  more details please check WindRiver VxWorks Documentation.

  \table 80%
    \header
        \li Feature
        \li Notes

    \row
        \li \c DSI_DSI_KERNEL
        \li

    \row
        \li \c IPNET_COREIP
        \li

    \row
        \li \c IPNET_DHCPC
        \li

    \row
        \li \c SDMMC_DEVICE
        \li

    \row
        \li \c SDMMC_HOST
        \li

    \row
        \li \c SDMMC_SDHC
        \li

    \row
        \li \c SDMMC_STORAGE
        \li

    \row
        \li \c SERVICE_UN
        \li

    \row
        \li \c SOCKET
        \li

    \row
        \li \c USB_EHCI
        \li

    \row
        \li \c USB_KEYBOARD
        \li

    \row
        \li \c USB_MOUSE
        \li

    \row
        \li \c USB_STORAGE
        \li

    \row
        \li \c EVDEV
        \li

    \row
        \li \c EVDEV_LIB
        \li

    \row
        \li \c EVDEV_TI_TSC2004_TS
        \li

    \row
        \li \c EVDEV_EETI_EXC7200_TS
        \li

    \row
        \li \c AUDIO
        \li

    \row
        \li \c GPUDEV_FSLVIVGPU
        \li

    \row
        \li \c HASH
        \li

    \row
        \li \c OPENSSL
        \li

    \row
        \li \c RANDOM_ENTROPY_INJECT
        \li

    \row
        \li \c IPNET_SSH
        \li

    \row
        \li \c USER_MANAGEMENT
        \li

    \row
        \li \c ICU
        \li

  \endtable

  The following config variables are added implicitly and you need to remove them:

  \table 80%
    \header
        \li Variable
        \li Notes

    \row
        \li \c _WRS_CONFIG_EVDEV_OPTIMIZED_MODE
        \li

    \row
        \li \c _WRS_CONFIG_EVDEV_DISPLAY_POINT_TRANSLATE
        \li

  \endtable

  You need to add the following variables to the config:

  \table 80%
    \header
        \li Variable
        \li Value
        \li Notes

    \row
        \li \c _WRS_CONFIG_RTP_SSP
        \li \c y
        \li

    \row
        \li \c _WRS_CONFIG_RTP_STACK_PROTECTOR
        \li \c y
        \li

  \endtable

  \section3 Example VIP configuration for i.MX 6 BSP
  For more details please check WindRiver VxWorks Documentation.

  \table 80%
    \header
        \li Layer
        \li Notes

    \row
        \li \c BUNDLE_POSIX
        \li This bundle is necessary for compatibility with POSIX-related
        functionalities which Qt requires.

    \row
        \li \c INCLUDE_TMP_DIR
            \c INCLUDE_RAM_DISK_FORMAT_HRFS
        \li Including these two components is necessary if you want to
            use \l {QTemporaryFile}. Note that you should also consider setting
            \c TMP_DIR_SIZE to appropriate value

    \row
        \li \c BUNDLE_RTP_DEVELOP
        \li

    \row
        \li \c BUNDLE_RTP_DEPLOY
        \li

    \row
        \li \c BUNDLE_STANDALONE_SHELL
        \li

    \row
        \li \c DRV_AUDIO_FSL_SSI
        \li

    \row
        \li \c DRV_AUDIO_FSL_SGTL5000
        \li

    \row
        \li \c DRV_FSL_SDHC_CTRL
        \li

    \row
        \li \c DRV_IMX_SDHC_CTRL
        \li

    \row
        \li \c INCLUDE_EHCI_INIT
        \li

    \row
        \li \c INCLUDE_FSL_IMX6Q_SABRELITE
        \li

    \row
        \li \c DRV_MMCSTORAGE_CARD
        \li

    \row
        \li \c DRV_SDSTORAGE_CARD
        \li

    \row
        \li \c INCLUDE_AUDIO_LIB_CORE
        \li

    \row
        \li \c INCLUDE_AUDIO_LIB_WAV
        \li

    \row
        \li \c INCLUDE_CUSTOM_ENTROPY_ADD
        \li

    \row
        \li \c INCLUDE_DEBUG_AGENT_START
        \li

    \row
        \li \c INCLUDE_DEFAULT_TIMEZONE
        \li

    \row
        \li \c INCLUDE_DISK_UTIL
        \li

    \row
        \li \c INCLUDE_DOSFS
        \li

    \row
        \li \c INCLUDE_DSAPARAM_CMD
        \li

    \row
        \li \c INCLUDE_END
        \li

    \row
        \li \c INCLUDE_EVDEV_LIB_CORE
        \li

    \row
        \li \c INCLUDE_EVDEV_LIB_KBD
        \li

    \row
        \li \c INCLUDE_EVDEV_LIB_KBD_MAP_US
        \li

    \row
        \li \c INCLUDE_EVDEV_LIB_PTR
        \li

    \row
        \li \c INCLUDE_GENDSA_CMD
        \li

    \row
        \li \c INCLUDE_GENRSA_CMD
        \li

    \row
        \li \c INCLUDE_GETADDRINFO
        \li

    \row
        \li \c INCLUDE_GETNAMEINFO
        \li

    \row
        \li \c INCLUDE_HRFS
        \li

    \row
        \li \c INCLUDE_HRFS_ACCESS_TIMESTAMP
        \li

    \row
        \li \c INCLUDE_HRFS_FORMAT
        \li

    \row
        \li \c INCLUDE_HRFS_HISPEED_WRITE_MODE
        \li

    \row
        \li \c INCLUDE_IFCONFIG
        \li

    \row
        \li \c INCLUDE_IO_REALPATH
        \li This component is needed to enable the use of the realpath function needed for \c QFileInfo

    \row
        \li \c INCLUDE_IPATTACH
        \li

    \row
        \li \c INCLUDE_IPCOM_SYSLOGD_CMD
        \li

    \row
        \li \c INCLUDE_IPCOM_SYSVAR_CMD
        \li

    \row
        \li \c INCLUDE_IPCOM_USE_RAM_DISK
        \li

    \row
        \li \c INCLUDE_IPCOM_USE_TIME_CMD
        \li

    \row
        \li \c INCLUDE_IPDHCPC
        \li

    \row
        \li \c INCLUDE_IPDNSC
        \li

    \row
        \li \c INCLUDE_IPD_CMD
        \li

    \row
        \li \c INCLUDE_IPFTPC
        \li

    \row
        \li \c INCLUDE_IPFTP_CMD
        \li

    \row
        \li \c INCLUDE_IPIFCONFIG_CMD
        \li

    \row
        \li \c INCLUDE_IPNETSTAT_CMD
        \li

    \row
        \li \c INCLUDE_IPNSLOOKUP_CMD
        \li

    \row
        \li \c INCLUDE_IPPING_CMD
        \li

    \row
        \li \c INCLUDE_IPROUTE_CMD
        \li

    \row
        \li \c INCLUDE_IPTRACE_ROUTE_CMD
        \li

    \row
        \li \c INCLUDE_IPWRAP_GETHOSTBYADDR
        \li

    \row
        \li \c INCLUDE_IPWRAP_GETHOSTBYNAME
        \li

    \row
        \li \c INCLUDE_IPWRAP_GETNAMEINFO
        \li

    \row
        \li \c INCLUDE_IPWRAP_IFNAME
        \li

    \row
        \li \c INCLUDE_IPWRAP_ROUTECMD
        \li

    \row
        \li \c INCLUDE_MMAP
        \li

    \row
        \li \c INCLUDE_PING
        \li

    \row
        \li \c INCLUDE_PIPES
        \li

    \row
        \li \c INCLUDE_POSIX_MAPPED_FILES
        \li

    \row
        \li \c INCLUDE_POSIX_PIPES
        \li

    \row
        \li \c INCLUDE_POSIX_PTHREAD_SCHEDULER
        \li

    \row
        \li \c INCLUDE_POSIX_SHM
        \li

    \row
        \li \c INCLUDE_RAM_DISK
        \li

    \row
        \li \c INCLUDE_RAM_DISK_FORMAT_HRFS
        \li

    \row
        \li \c INCLUDE_RANDOM_NUM_GEN
        \li

    \row
        \li \c INCLUDE_ROMFS
        \li

    \row
        \li \c INCLUDE_ROUTECMD
        \li

    \row
        \li \c INCLUDE_SC_PIPE
        \li

    \row
        \li \c INCLUDE_SC_POSIX_PIPE
        \li

    \row
        \li \c INCLUDE_SD_BUS
        \li

    \row
        \li \c INCLUDE_SECURITY
        \li

    \row
        \li \c INCLUDE_SEC_KEY_STORE_CMD
        \li

    \row
        \li \c INCLUDE_SHELL
        \li

    \row
        \li \c INCLUDE_SSH
        \li

    \row
        \li \c INCLUDE_STANDALONE_SYM_TBL
        \li

    \row
        \li \c INCLUDE_STARTUP_SCRIPT
        \li

    \row
        \li \c INCLUDE_TMP_DIR
        \li

    \row
        \li \c INCLUDE_UN_COMP
        \li

    \row
        \li \c INCLUDE_USB_GEN2_KEYBOARD
        \li

    \row
        \li \c INCLUDE_USB_GEN2_MOUSE
        \li

    \row
        \li \c INCLUDE_USB_GEN2_STORAGE_INIT
        \li

    \row
        \li \c INCLUDE_USER_DATABASE
        \li

    \row
        \li \c INCLUDE_USER_IDENTIFICATION
        \li

    \row
        \li \c INCLUDE_VRFS
        \li

    \row
        \li \c INCLUDE_VXBUS_SHOW
        \li

    \row
        \li \c DRV_TOUCH_SCREEN_TI_TSC2004
        \li

    \row
        \li \c DRV_TOUCH_SCREEN_EETI_EXC7200
        \li

    \row
        \li \c INCLUDE_FBDEV_FSLIPU_0
        \li

    \row
        \li \c INCLUDE_FBDEV_SPLASH
        \li

    \row
        \li \c INCLUDE_GPUDEV_FSLVIV_API
        \li

    \row
        \li \c INCLUDE_GPUDEV_FSLVIV_API_INIT
        \li

  \endtable

  The following components are added implicitly and you need to remove them:

  \table 80%
    \header
        \li Layer
        \li Notes

    \row
        \li \c INCLUDE_FTP
        \li

    \row
        \li \c INCLUDE_SHELL_SECURITY
        \li

  \endtable

  \section4 VIP Parameters

  You need to add the following parameters for Qt to run properly on VxWorks:

  \table 80%
    \header
        \li Parameter
        \li Example value
        \li Notes

    \row
        \li \c SEC_VAULT_KEY_ENCRYPTING_PW
        \li \c '"vxTarget"'
        \li Example value

    \row
        \li \c UDB_STORAGE_PATH
        \li \c '"/ram/vxUserDB.txt"'
        \li Example value

    \row
        \li \c UDB_HASH_KEY
        \li \c '"123456789"'
        \li Example value

    \row
        \li \c UDB_HASH_KEY_LEN
        \li \c 9
        \li Example value, see previous

    \row
        \li \c FSLVIV_RTP_COMMAND_BUFFER_QUEUE
        \li \c 32
        \li For 'arm' architecture

    \row
        \li \c SYS_CLK_RATE
        \li \c 100
        \li

    \row
        \li \c RTP_PTHREAD_STACK_SIZE_DEFAULT
        \li \c 131072
        \li

    \row
        \li \c TMP_DIR_SIZE
        \li \c 614400
        \li Minimum value for passing Qt internal tests

    \row
        \li \c NUM_FILES
        \li \c 300
        \li

    \row
        \li \c RTP_FD_NUM_MAX
        \li \c 300
        \li

    \row
        \li \c HRFS_DEFAULT_MAX_FILES
        \li \c 300
        \li

  \endtable

  \section1 Building Qt 6 for VxWorks

  \section2 Building Qt 6 for Host

  When cross-building Qt 6 for VxWorks, it's best practice to use host tools
  that use the same source code as cross-build does. This requires building Qt 6
  for host first, but only with limited subset of submodules:
    \list
    \li qtbase
    \li qtdeclarative
    \li qtquick3d
    \li qtshadertools
    \endlist

  Make sure to have all necessary prerequisites for building Qt 6 for host. Check
  details in \l{Building Qt Sources}.

  \section3 Running the Configure Script

  The commands to configure, build, and install Qt 6 for host are the following:

  \badcode
    ./configure \
        -cmake-generator "Ninja" \
        -extprefix <path/to/Qt6/host/installation/dir> \
        -submodules qtbase,qtdeclarative,qtquick3d,qtshadertools \
        -nomake tests \
        -nomake examples \
        -- \
        -B <host/build/directory>
    cd <host/build/directory>
    ninja
    ninja install
  \endcode

  These commands install Qt 6 for the host in
  \c {<path_to_Qt 6_host_installation_dir>}.

  \section2 Building Qt 6 for the Target

  \section3 Setting Up the Build Environment

  Before you run configure and build Qt 6, you must open \e {VxWorks Development Shell} in command
  prompt.

  \list
  \li Linux:
  \badcode
  cd <VxWorks installation directory>
  ./wrenv.sh -p vxworks
  export WIND_CC_SYSROOT=<path to VxWorks VSB directory>
  \endcode

  \li Windows:
  \badcode
  cd <VxWorks installation directory>
  wrenv -p vxworks
  export WIND_CC_SYSROOT=<path to VxWorks VSB directory>
  \endcode
  \endlist

  \section3 Preparing the Custom CMake Toolchain File

  To include graphics libraries from the BSP, you need to first create a CMake toolchain file.
  An example CMake toolchain file for BD-SL-i.MX6 device:

  \badcode
  # Copyright (C) 2024 The Qt Company Ltd.
  # SPDX-License-Identifier: BSD-3-Clause

  if(QT_VXWORKS_TOOLCHAIN_FILE)
      set(_original_toolchain_file "${QT_VXWORKS_TOOLCHAIN_FILE}")
  elseif(DEFINED ENV{QT_VXWORKS_TOOLCHAIN_FILE})
      set(_original_toolchain_file "$ENV{QT_VXWORKS_TOOLCHAIN_FILE}")
  else()
      message(FATAL_ERROR "QT_VXWORKS_TOOLCHAIN_FILE is not set.")
  endif()

  if(NOT EXISTS "${_original_toolchain_file}")
      message(FATAL_ERORR "${_original_toolchain_file} doesn't exists.")
  endif()

  include("${_original_toolchain_file}")
  unset(_original_toolchain_file)

  list(APPEND CMAKE_TRY_COMPILE_PLATFORM_VARIABLES QT_VXWORKS_TOOLCHAIN_FILE)

  set(_common_lib_path "${CMAKE_SYSROOT}/usr/lib/common")
  set(EGL_INCLUDE_DIR ${CMAKE_SYSROOT}/usr/h/public CACHE PATH "Path to EGL include directory" FORCE)
  set(EGL_LIBRARY ${_common_lib_path}/libgfxFslVivEGL.so CACHE PATH "Path to EGL lib" FORCE)
  set(GLESv2_INCLUDE_DIR ${CMAKE_SYSROOT}/usr/h/public CACHE PATH "Path to GLES include directory" FORCE)
  set(GLESv2_LIBRARY ${_common_lib_path}/libgfxFslVivGLESv2.so CACHE PATH "Path to GLES lib" FORCE)

  set(VxWorksPlatformGraphics_DEFINES "-D_FSLVIV")
  set(VxWorksPlatformGraphics_LIBRARIES_PACK
      "${_common_lib_path}/libgfxFslVivGAL.so"
      "${_common_lib_path}/libgfxFslVivGLSLC.so"
      "${_common_lib_path}/libgfxFslVivVDK.so"
      "${_common_lib_path}/libxml.so"
  )

  set(VxWorksPlatformGraphics_REQUIRED_LIBRARIES
      ${VxWorksPlatformGraphics_LIBRARIES_PACK}
      ${EGL_LIBRARY}
      ${GLESv2_LIBRARY}
  )
  unset(_common_lib_path)
  \endcode

  \section3 Running Qt 6 Configure for the Target

  Below is an example build configuration for the BD-SL-i.MX6. For most VxWorks boards
  the configure command looks very similar. By default, Qt 6 is configured to
  use shared libraries. To build Qt 6 statically, add \c -static option to configure.

  Make sure that {WIND_CC_SYSROOT} environment variable is set to VxWorks VSB root
  directory.

  \badcode
    ./configure \
        -cmake-generator "Ninja" \
        -icu \
        -eglfs \
        -qpa eglfs \
        -submodules "qtbase,qtdeclarative,qtmultimedia,qtquick3d,qtgraphs,qtimageformats,qtsvg,qtshadertools,qtvirtualkeyboard" \
        -- \
        -B <target/build/directory> \
        -DQT_VXWORKS_TOOLCHAIN_FILE=<path/to/BDP/toolchain.cmake> \
        -DFEATURE_vulkan=OFF \
        -DQT_QMAKE_TARGET_MKSPEC=vxworks-clang \
        -DQT_HOST_PATH=<path/to/Qt6/host/installation/dir> \
        -DCMAKE_STAGING_PREFIX:PATH=<path/to/Qt6/target/installation/dir> \
        -DCMAKE_TOOLCHAIN_FILE=<path/to/cmake/for/graphics/file/created/above> \
  \endcode

  In case of building for DKM rather than RTP, use \c -static option and change the
  \c CMAKE_TOOLCHAIN_FILE value to \c {"$WIND_CC_SYSROOT/mk/dkm.toolchain.cmake"}

  It is recommended to build Qt 6 using a \e{shadow build}. See \l {Qt Configure Options}
  for more information.

  After configuration, build and install Qt 6 for VxWorks with these commands:

  \badcode
  cd <host build directory>
  ninja
  ninja install
  \endcode

  \section1 Platform Plugins for VxWorks Devices

  Qt for VxWorks supports EGLFS platform plugin for a \e {native window} substitution.
  Read more about its configuration in \l{embedded eglfs}{EGLFS}.

  \section1 Building Qt Applications

  To build a Qt application, you must set the QT_VXWORKS_TOOLCHAIN_FILE as an environment variable
  or as a define.

  An example to build the clocks Qt demo:
  \badcode
  export WIND_CC_SYSROOT=<path/to/VxWorks/VSB/directory>
  export QT_VXWORKS_TOOLCHAIN_FILE=<path/to/the/BSP/toolchain.cmake>
  <path/to/Qt6/target/installation/dir>/bin/qt-cmake -G Ninja -S ~/Qt/Examples/Qt-6.8.0/demos/clocks -B <path/to/build/directory>
  cd <path/to/build/directory>
  ninja
  \endcode

  \section1 Running Qt Applications

  The following example shows how to start an application when Qt 6 is built using
  shared libraries. With a statically built Qt 6, you don't need to use the
  \c LD_LIBRARY_PATH environment variable for the Qt libraries, but it needs to point
  to the location of VxWorks shared libraries (for example libc and OpenGL ES 2.0).
  It is not needed for Qt 6 static libraries.

  \badcode
  putenv "LD_LIBRARY_PATH=/sd0:1/lib"
  cd "/sd0:1"
  rtpSp("<Qt 6_app>", 200, 0x100000, 0, 0x01000000)
  \endcode

  \section1 Limitations

  \section2 Video Memory

  Systems with a fixed amount of dedicated video memory may need extra care
  before running Qt application based on Qt Quick or classes like
  \l{QOpenGLWidget}. The default setting might be insufficient for such applications,
  especially when they are displayed on a high resolution (for example, full HD)
  screen. In this case they might start failing in unexpected ways. It is
  therefore recommended to ensure that there is at least 128 MB of GPU memory
  available. For systems that do not have a fixed amount of memory reserved for
  the GPU this is not an issue.

*/
