// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

    /*!
    \page creator-developing-baremetal.html
    \previouspage creator-reference.html

    \ingroup creator-reference-devices

    \title Developing for Bare Metal Devices

    \brief Create kits to use Bare Metal toolchains installed on the computer
    to build applications for and run and debug them on connected Bare Metal
    devices.

    Run and debug applications on small devices that are not supported
    by the remote Linux device plugin by using GDB or a hardware debugger.

    \note Enable the Bare Metal plugin to use it.

    Install Bare Metal toolchains on the computer to build applications for
    Bare Metal devices. Connect the devices to the computer to run and debug
    applications on them.

    \note If you use qmake to build the project and the device does not have
    Qt libraries, you need a Qt installation that meets the requirements in
    \l{Self-built Qt versions}. In addition, the \c mkspecs directory needs
    to be complete enough to parse .pro files.

    The following toolchains are supported for building applications:

    \list
        \li GCC: Microchip Technology (AVR, AVR32, PIC16, PIC32),
            NXP Semiconductors (ColdFire, M68K), Texas Instruments (MSP430),
            National Semiconductor (CR16C), Renesas Electronics (M32R, M32C,
            RL78, RX, SuperH, V850), Tensilica XTENSA (ESP8266, ESP32), RISC-V,
            Arm
        \li \l{https://www.iar.com/iar-embedded-workbench/}{IAR EW}:
            Microchip Technology (AVR, AVR32), NXP Semiconductors
            (ColdFire, M68K), Texas Instruments (MSP430),
            National Semiconductor (CR16C), Renesas Electronics (78K,
            M16/R8C, M32C, R32C, RH850, RL78, RX, SuperH, V850),
            STMicroelectronics (STM8), 8051, RISC-V, Arm
        \li \l{https://www.keil.com/product/}{Keil}: Arm, C51 (8051),
            C251 (80251), C166 (C16x, XC16x)
        \li \l{http://sdcc.sourceforge.net/}{SDCC}: STMicroelectronics (STM8),
            8051
    \endlist

    The bare metal device type accepts custom GDB commands that you specify in
    the device preferences. You can specify the commands to execute when connecting
    using a particular debug server provider.

    \section1 Debug Server Providers

    The following debug server providers are supported when using GDB:

    \list
        \li \l {Set up EBlink}{EBlink}
        \li \l {Set up J-Link}{J-Link}
        \li \l {Set up OpenOCD}{OpenOCD}
        \li \l {Set up ST-Link}{ST-Link}
    \endlist

    ST-Link and J-Link debug server providers can be used together with
    the \l {Set up the uVision IDE}{uVision IDE}.

    To create connections to bare metal devices using a debug server provider,
    go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal} and select
    \uicontrol Add.

    The available settings depend on the debug server provider.

    \sa {Add kits}, {Enable and disable plugins},
    {Bare Metal}{How To: Develop for Bare Metal}
*/

/*!
    \page creator-how-to-eblink.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-bare-metal

    \title Set up EBlink

    \l{https://github.com/EmBitz/EBlink}{EBlink} is an ARM Cortex-M debug tool
    that supports squirrel scripting, live variables, and hot-plugging.

    \image {qtcreator-baremetal-eblink.webp} {EBlink in the Bare Metal tab in Devices preferences}

    To set preferences for \EBlink:

    \list 1

        \include creator-baremetal-settings.qdocinc {baremetal-common} {EBlink}

        \li In \uicontrol {Script file}, enter the path
            to a device script file.

        \li In \uicontrol {Verbosity level}, enter the level of
            verbose logging.

        \li Select \uicontrol {Connect under reset} to use
            the ST-Link interface. Clear it for hot-plugging.

        \li In \uicontrol Type, select the interface type.

        \li In \uicontrol Speed, enter the interface speed between
            120 and 8000 kilohertz (kHz).

        \li Select \uicontrol {Disable cache} to disable the
            \EBlink flash cache.

        \li Select \uicontrol {Auto shutdown} to automatically
            shut down the \EBlink server after disconnecting.

        \include creator-baremetal-settings.qdocinc baremetal-init-reset

    \endlist

    \sa {Bare Metal}{How To: Develop for Bare Metal},
    {Developing for Bare Metal Devices}
*/

/*!
    \page creator-how-to-jlink.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-bare-metal

    \title Set up J-Link

    \l{https://www.segger.com/products/debug-probes/j-link/}{J-Link} is a line
    of debug probes by Segger.

    \image {qtcreator-baremetal-jlink.webp} {J-Link in the Bare Metal tab in Devices preferences}

    To set preferences for J-Link debug probes:

    \list 1

        \include creator-baremetal-settings.qdocinc {baremetal-common} {J-Link}

        \li In \uicontrol {Host interface}, select the connection
            type, IP or USB, or use the default connection.

        \li In \uicontrol {Target interface}, select the target interface type.

        \li In \uicontrol Speed, enter the interface speed in kHz.

        \li In \uicontrol Device, select the device to connect to.

        \li In \uicontrol {Additional arguments}, enter arguments for the
            commands.

        \include creator-baremetal-settings.qdocinc baremetal-init-reset

    \endlist

    \sa {Bare Metal}{How To: Develop for Bare Metal},
    {Developing for Bare Metal Devices}
*/

/*!
    \page creator-how-to-openocd.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-bare-metal

    \title Set up OpenOCD

    \l{http://openocd.org}{OpenOCD} (Open On-Chip Debugger) is an on-chip debug
    solution for targets based on the ARM7 and ARM9 family with Embedded-ICE
    (JTAG) facility. It enables source level debugging with the GDB compiled
    for the ARM architecture.

    \image {qtcreator-baremetal-openocd.webp} {OpenOCD in the Bare Metal tab in Devices preferences}

    To set preferences for \OpenOCD:

    \list 1

        \include creator-baremetal-settings.qdocinc {baremetal-common} {OpenOCD}

        \li In \uicontrol {Root scripts directory}, enter the
            path to the directory that has configuration scripts.

        \li In \uicontrol {Configuration file}, enter the path
            to the device configuration file.

        \li In \uicontrol {Additional arguments}, enter
            arguments for the commands.

        \include creator-baremetal-settings.qdocinc baremetal-init-reset

    \endlist

    \sa {Bare Metal}{How To: Develop for Bare Metal},
    {Developing for Bare Metal Devices}
*/

/*!
    \page creator-how-to-stlink.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-bare-metal

    \title Set up St-Link

    \l{https://www.st.com/en/development-tools/stlink-v3-bridge.html}
    {ST-LINK Utility} is used for programming STM32 microcontrollers.

    \image {qtcreator-baremetal-stlink.webp} {St-Link  in the Bare Metal tab in Devices preferences}

    To set preferences for St-Link:

    \list 1

        \include creator-baremetal-settings.qdocinc {baremetal-common} {St-Link}

        \li In \uicontrol {Verbosity level}, enter the level of
            verbose logging.

        \li Select \uicontrol {Extended mode} to continue
            listening for connection requests after the connection is closed.

        \li Select \uicontrol {Reset on connection} to
            reset the board when the connection is created.

        \li In \uicontrol Version, select the transport
            layer type supported by the device.

        \include creator-baremetal-settings.qdocinc baremetal-init-reset

    \endlist

    \sa {Bare Metal}{How To: Develop for Bare Metal},
    {Developing for Bare Metal Devices}
*/

/*!
    \page creator-how-to-uvision.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-bare-metal

    \title Set up the uVision IDE

    \l{http://www.keil.com/support/man/docs/uv4/uv4_overview.htm}{uVision} is
    an IDE for developing applications for embedded devices. To debug
    applications, use uVision Simulator, or debug directly on hardware by using
    St-Link and J-Link.

    The \uicontrol {Peripheral Registers} view in Debug mode shows the current
    state of peripheral registers. The view is hidden by default.

    \section1 uVision Simulator

    \image {qtcreator-baremetal-uvision-simulator.png} {uVision Simulator in the Bare Metal tab in Devices preferences}}

    To set preferences for uVision Simulator:

    \list 1

        \include creator-baremetal-settings.qdocinc {uvision-common} {uVision Simulator}

        \li Select \uicontrol {Limit speed to real-time} to limit
            the connection speed.

        \li Select \uicontrol Apply to add the debug server provider.

       \endlist

    \section1 uVision St-Link or JLink Debugger

    \image {qtcreator-baremetal-uvision-st-link.png} {uVision St-Link in the Bare Metal tab in Devices preferences}

    To set preferences for uVision St-Link or JLink Debugger:

    \list 1

        \include creator-baremetal-settings.qdocinc {uvision-common} {uVision St-Link or uVision JLink}

        \li In \uicontrol {Adapter options} specify the adapter
            interface type and speed in MHz.

        \li Select \uicontrol Apply to add the debug server provider.

    \endlist

    \sa {Bare Metal}{How To: Develop for Bare Metal},
    {Developing for Bare Metal Devices}
*/

/*!
    \page creator-how-to-add-bare-metal-devices.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-bare-metal
    \ingroup creator-how-to-manage-kits

    \title Add Bare Metal devices

    Run and debug applications on small devices that are not supported
    by the remote Linux device plugin by using GDB or a hardware debugger.

    To add a bare metal device:

        \list 1

           \li Go to \preferences > \uicontrol Devices > \uicontrol Devices.
               \image {qtcreator-baremetal-devices.png} {Bare Metal tab in Devices preferences}
           \li Select \uicontrol Add > \uicontrol {Bare Metal Device} >
                \uicontrol {Start Wizard}.

           \li In \uicontrol {Debug server provider}, select a debug
               server provider.

            \li Select \uicontrol Finish to return to > \uicontrol Devices.

            \li Select \uicontrol Apply to add the device.

        \endlist

    \section1 Add the device to a kit

    To add a kit for building applications and running them on bare metal
    devices, go to \preferences > \uicontrol Kits and select \uicontrol Add.

    \image {qtcreator-preferences-kits-baremetal.webp} {Bare Metal device selected in Kits preferences}

    Build applications for and run them on bare metal devices
    in same way as for and on the desktop.

    \sa {Add kits}, {Build for many platforms},
    {Bare Metal}{How To: Develop for Bare Metal}, {Run on many platforms},
    {Developing for Bare Metal Devices}
*/
