/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
//! [building monolith]

    In this tutorial, we build a monolith INTEGRITY project for a Qt example
    application. You can select any Qt example application that uses the
    \l {Supported Qt Modules} {supported Qt modules}.

    Before you can build a monolith INTEGRITY project, you need to prepare your
    build environment for the \c qmake build tool. You can do this by running
    the script \e {~/setEnvironment.sh} that you created in
    \l {Creating Script for Running Exports}.

    Run the following commands in a terminal:

    \badcode
    source ~/setEnvironment.sh
    <Qt installation path>/qtbase/bin/qmake <Qt example application path>/<projectname>.pro
    make
    \endcode

    The \c qmake tool must be called under the Qt installation path
    (<Qt installation path>), where you installed the Qt sources in
    \l {Getting Qt Source Code}.

    <Qt example application path>/<projectname>.pro is the installation path of
    the Qt example application project file that the monolith INTEGRITY project
    will be built for.

    \section1 Building Monolith Project

    To build a monolith INTEGRITY project, create an empty directory for your
    project in your home folder. In the steps below, we use the directory name
    \e {mymonolith}.

    \section2 Defining Project with Project Wizard

    Launch MULTI Launcher and select \uicontrol {File} > \uicontrol
    {Create New Project}. Define your monolith project with Project Wizard:

    \list 1
        \li In the \uicontrol {Project name} tab, fill in the \uicontrol {Directory}
        field with the directory you just created.
        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Operating System} tab, select \e {INTEGRITY}
        from the \uicontrol {Operating System} list.
        \note The \uicontrol {OS Distribution Directory} field must contain your
        INTEGRITY installation directory (in our example, \e{mymonolith}).
        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Processor Family} tab, select \uicontrol {ARM}.
        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Target Board} tab, select \uicontrol {ARM Cortex-A9 Platform }
        from the target board list.
        \li Select \uicontrol {Finish}.
    \endlist

    \image project-wizard

    After selecting \uicontrol {Finish} in Project Wizard, Project Manager is
    opened.

    \section2 Project Manager Settings

    With Project Manager you can define the settings for the monolith project:

    \list 1
        \li In the \uicontrol {Select Item to Add} dialog page, select \uicontrol
        {Monolith} from the \uicontrol {Create New} list.

        \image select-item-to-add

        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Settings for Monolith} dialog, define the settings:
        \list
            \li \uicontrol {Source Code Directory} is your project directory
            (in our example, \e {mymonolith}).
            \li \uicontrol {Project Name} is the name of your project. In our
            example, we use the name \e{myproject}.
            \li \uicontrol {Language} must be \uicontrol {C}. The Qt projects are
            C++ projects, but this will be configured later.
            \li Select \uicontrol {Next}.
            \li \uicontrol {Use Shared Libraries} should not be selected.
            \li Select \uicontrol {Next}.
        \endlist
        \li In the \uicontrol {Configure number of Virtual AddressSpaces} dialog
        page, select the checkbox \uicontrol {Names of Virtual Address Spaces} and
        type \e{galcore}.
        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Settings for Kernel} dialog page, type the name of
        your kernel.
        \li Select \uicontrol {Debugging}, \uicontrol {Dynamic Load} and
        \uicontrol {ResourceManager} from the \uicontrol {Kernel Libraries} list.

        \image kernel-settings

        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Settings for OS Module Selection} dialog page,
        select \uicontrol {File System (User Configured)} and \uicontrol
        {GHnet IPv4 Stack (Virtual)} from the \uicontrol {OS Module} list.
        \li Select \uicontrol {Next}.
        \li In the \uicontrol {Settings for File System (User Configured)} dialog
        page, select a filesystem that your monolith project supports.

        In our example, we have selected \uicontrol {MSDOS FAT} from the
        \uicontrol {Libraries} list.
        \li Select \uicontrol {Finish}.
        \li In the \uicontrol {Settings for Add File System Clients} dialog page,
        select \uicontrol {Finish}.
    \endlist

    \section2 Adding File System Mount Point

    You need to configure the file system to use the first partition of the
    micro SD card. In the MULTI Project Manager view, you see a tree structure
    of your monolith project:

    \list 1
        \li Right-click the file \e {mounttable.c} to open the context menu.
        \li Select \uicontrol {Modify Project} >
        \uicontrol {Add INTEGRITY File System Mount Point}.
        \li In the \uicontrol {Settings for FS MountPoint} dialog, define
        the settings:
        \list
            \li Type \e {/} to \uicontrol {Mount Directory}.
            \li Select \uicontrol {Next}.
            \li \uicontrol {File System Type} is \e {MSDOS FAT}.
            \li Select \uicontrol {Next}.
            \li Select the \uicontrol {Use Physical Device} radio button.
            \li Type \e {SDCardDev1} to the \uicontrol {Device} field.
            \li \uicontrol {Slice} is \e {a}.
            \li Select \uicontrol {Finish}.
        \endlist
    \endlist

    \section2 Galcore VAS Settings

    Next, define the virtual address space (VAS) settings for your project.

    In the MULTI Project Manager view, you see a tree structure of your monolith
    project:

    \list 1
        \li Double-click the .int file in your project (1) (in the steps below,
        \e {myproject.int}).
        \li In the opened window, double-click the galcore virtual address
        space (VAS) area (2).

        \image project-view

        \li \uicontrol {VirtualAddressSpace Options} dialog is opened.
        \li In the \uicontrol {Attributes} tab, select the values defined in
        \l {Values in Attributes Tab}.
        \li Select \uicontrol {OK}.
        \li In the galcore virtual address space area, double-click the
        \uicontrol {Task Initial} area (3).

        \image project-view-2

        \li Select the \uicontrol {Start Automatically} check box.
        \li Select \uicontrol {OK}.
    \endlist

    \section3 Values in Attributes Tab

    Add the following attribute values for the virtual address space:

    \table 80%
        \header \li Attribute \li Value
        \row
            \li Maximum Priority
            \li 255
        \row
            \li Maximum Weight
            \li 255
        \row
            \li Memory Pool Size
            \li 2000P
        \row
            \li Heap Size
            \li 0X2000000
        \row
            \li Heap Extension Reserved Size
            \li 0x20000
        \row
            \li Arguments
            \li Leave blank.
        \header \li Checkbox \li Value
        \row
            \li Create Extra Virtual Memory Regions
            \li Select the checkbox.
    \endtable

    \section2 Editing Galcore Project

    You need to edit a number of files in the monolith project.

    \section3 File galcore.c

    \list 1
        \li Select \e{galcore.c} from the tree structure in the MULTI Project
        Manager view.
        \li Double-click the file to open it for editing.
        \li Add the following code to \e{galcore.c}:

    \badcode
    #include <INTEGRITY.h>
    #include <stdlib.h>
    #include <stdio.h>
    extern Error GalCore_TaskInit(void);
    int main(void) {
        Error E;
        E = GalCore_TaskInit();
        if (E != Success) {
            printf("Failed to start GalCore tasks\n");
        }
        Exit(0);
    }
    \endcode
    \endlist

    \section3 File galcore.gpj

    \list 1
        \li Select \e{galcore.gpj} from the tree structure in the MULTI Project
        Manager view.
        \li Right-click the file to open the context menu.
        \li Select \uicontrol{Edit}.
        \li Add the file \e{libgalcore.a} to \e{galcore.gpj}.
    \endlist

    Contents of \e{galcore.gpj} should be as follows:

    \badcode
    #!gbuild
    #component integrity_virtual_address_space
    [Program]
        -lgalcore
    tgt/INTEGRITY.ld
    galcore.c
    \endcode

    \section3 File kernel.gpj

    \list 1
        \li Select \e{kernel.gpj} from the tree structure in the MULTI Project
        Manager view.
        \li Right-click the file to open the context menu.
        \li Select \uicontrol{Edit}.
        \li Add the file \e{libgalcore-iod.a} to \e{kernel.gpj}.
    \endlist

    Contents of \e{kernel.gpj} should be as follows:

    \badcode
    #!gbuild
    #component integrity_kernel_monolith
    [Program]
        -kernel
        -ldebug
        -lload
        -lres
        -lgalcore-iod
    tgt/default.ld
    myproject_kernel.c
    global_table.c
    \endcode

    \section3 File monolith.gpj

    \list 1
        \li Select \e{monolith.gpj} from the tree structure in the MULTI Project
        Manager view.
        \li Righ-click the file to open the context menu.
        \li Select \uicontrol{Edit}.
        \li Add the additional library directory \e {$(__LIBS_DIR_BASE)/Vivante}.
    \endlist

    Contents of \e{monolith.gpj} should be as follows:

    \badcode
    #!gbuild
    #component integrity_monolith
    [INTEGRITY Application]
        -non_shared
       -I$__OS_DIR/modules/ghs/ghnet2/source/kernel/integrity/ip4server :sourceDir=$__OS_DIR/modules/ghs/ghnet2/source/kernel/integrity/ip4server
       -L$(__LIBS_DIR_BASE)/Vivante
    tgt/default.bsp
    myproject.int
    galcore.gpj [Program]
    myproject_kernel.gpj [Program]
    my_ivfsserver_module.gpj [Program]
    ip4server_module.gpj [Program]
    \endcode

    \section3 .int File

    \list 1
    \li Select the \e {.int} file of your project from the tree structure in the MULTI Project
    Manager view.
    \li Right-click the file to open the context menu.
    \li Select \uicontrol{Edit}.
    \li Add the following lines at the end of the file.

    \note Replace </path/to/your/app/executable> with a path to your application executable.

    \badcode
    AddressSpace
        Name    myappname
        Filename    /path/to/your/app/executable
        MemoryPoolSize 0x2000000
        Language    C++
        HeapSize    0x6000000

        Task Initial
            StackSize    0x30000
            StartIt    true
        EndTask
        HeapExtensionReservedSize    0x2000000
    EndAddressSpace
    \endcode
    \endlist

    \section2 Building monolith.gpj

    Open \e{monolith.gpj} from the tree structure in the MULTI Project Manager
    view. To build the project:

    \list 1
        \li Right-click \e{monolith.gpj} to open the context menu.
        \li Select \uicontrol{Build}.
    \endlist

    Your monolith project is now ready to be packaged for U-Boot.
//! [building monolith]
*/