/* ------------------------------------------------------------------------------------------------ */
/* FILE :        readme.txt                                                                         */
/*                                                                                                  */
/* CONTENTS :                                                                                       */
/*               mAbassi SMP RTOS: description for ARM Cortex A53 / Xilinx SDK (Free version)       */
/*                                                                                                  */
/*                                                                                                  */
/* Copyright (c) 2014-2018, Code-Time Technologies Inc. All rights reserved.                   		*/
/*                                                                                                  */
/* Code-Time Technologies retains all right, title, and interest in and to this work                */
/*                                                                                                  */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS                          */
/* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                                       */
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL                          */
/* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR                             */
/* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,                            */
/* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR                            */
/* OTHER DEALINGS IN THE SOFTWARE.                                                                  */
/*                                                                                                  */
/*                                                                                                  */
/*  $Revision: 1.8 $                                                                                */
/*  $Date: 2017/10/31 18:34:19 $                                                                    */
/*                                                                                                  */
/* ------------------------------------------------------------------------------------------------ */


*** IMPORTATNT ***
   This is the free version, mAbassi's kernel will start rejecting requets after a while.

   Contact Code Time if interested in having access to the evaluation package:
      - All drivers & Demos
      - Library re-entrance protection
      - Software utilities, e.g. System Call layer

Quick overview at this level:

   - mAbassi build options (OS_DEMO set to -ve value) are defined in ../Platform/inc/AbassiLib.h
   - mAbassi object code (a library) is located in ../Platform/lib
   - mAbassi include file and tool definitions are located in ../Abassi, one level above
   - The demos source code is located in the directory ../Share/src, one level above
   - The demos include files are located in the directory ../Share/inc, one level above
   - The SD/MMC webserver html files are located in ../Share/fs, one level above
   - The target specific source files are located in the directory ../Platform/src, one level above
   - The target specific include files are located in the directory ../Platform/inc, one level above
   - The tool/target specific source files are located in the directory ./src
   - The tool/target specific include files are located in the directory ./inc
   - The SDK workspace is ./Workspace
   - All demo projects are located in individual directories in ./Workspace
   - The RTOS drivers are located in ../Drivers, one level above

   - 1 library are provided in ../Platform/lib:
         lib_mAbassi_EVAL_GCC_ULTRASCALE_A53.a         : mAbassi without NEWLIB re-entrance protection

   - For all projects, these definitions must be set:
        OS_PLATFORM     : must be set to 0x7753	(UltrasScale+ - A53)
        OS_DEMO         : must be set to a -ve value
        OS_N_CORE       : must be set to 4
        OS_NEWLIB_REENT : must be set to 0
        OS_TIMER_US     : The application timer tick period can be set to a different value from the
                          one that was used to build the libraries. The value used in the library is
                          avaialble in ../Platform/inc/AbassiLib.h. Setting the proper value of
                          OS_TIMER_US will convert all human time to the correct # timer tick.
                          One demo using a different OS_TIME_US setting is Demo #50.

        DO NOT SET any other Abassi/mAbassi/ASM build options otherwise there will be a mismatch
        between RTOS data structures used in the library and the ones used in the application.
        Changing any other build options will most likely result in a crash of the application 

        *** The library was built using the configuration settings defined in AbassiLib.h located
            in ../Platform/inc


/* ------------------------------------------------------------------------------------------------ */
/* Building and debugging																			*/

   - The workspace .metadata must be re-created for your computer.
     Go through these menus:
     "File" -> "Import..."
     Expand "General"
     Select "Existing Projects into Workspace"
     Click "Next"
     Select Root Directory / Browse
        . . . . /mAbassi_SMP_CortexA53_XSDK/Workspace
       DO NOT check the box "Copy projects into workspace"
       DO NOT check the box "Add project to working sets"
     Click on "Finish"

      Background:
         Recent SDK has become quite unfriendly to SMP as only an application built with a reference
         to a BSP for core #N can be downloaded to core #N.
         The direct way to debug an SMP application is to download the app to core #0 and then
         attach all other cores without code download.  But doing so does not provide visibility
         of the symbols on non-#0 cores.  To get the symbols and debug info, the symbols must be
         loaded by right-clicking on the core, then select "Symbol Files..." and specifying the
         elf file to use.  Doing this manual operation becomes quite cumbersome after a while.

      How we overcome:
         The way used with mAbassi is to download the same application on all cores so there are
         no needs for manual symbols download.  To overcome the core # restriction, dummy projects
         are created for each of the cores: Core0, Core1, ... etc  Also, dummy BSPs are created for
         each of the dummy project and are named Core0_bsp, Core1_bsp, ... etc.  Each of these bsp
         are targetted for a different core and the CoreN project references CoreN_bsp.
         When the BSP are created, before building them, the make coomand is set to "echo" as
         it will do nothing and not fill the workspace with the unused bsp code. Plus all directories
         under psu_cortex??_N are deleted to further get rid of unused code.
         All above steps have been performed and when importing thje workspace, all the
         required project & BSP will be pulled.

      Building:
         When an SMP application is built, it uses mAbassi_bsp as its BSP but it does not refer to
         it.  Unless stuff for the BSP is needed by the appl;ication. mAbassi & its support S/W
         use almost nothing from the bsp. By not referencing it, it avoids having to rebuild the bsp
         every time a "build clean" is done on the application.
              Note: you need to manually build the BSP once.
         At the end of the application build, the generated .elf file is copied in all the CoreN
         projects in their Debug directories.
              Note: the first time you do a build, you need to refreash all projects CoreN after the
                    first build othewise the .elf files in the dummy project will not be seen. 

      Debugging:
         To create the debug configuration, you only need  one for all SMP project in the workspace,
         proceed as following:
             Create a "Xilinx C/C++ application (System Debugger)"
             In the "Target Setup" tab :
                 "Debug Type:         : standalone Application Debug
                 "Hardware" platform  : ZCU102-ES2_hw_platform
                 "Bitstream file"     : design_1_wrapper_bit
                 "Initialization file": ps7_init.tcl
                  Check all the boxes

             In the "Application" tab :
                  Checkmark all coree and you should see for all of them:
                      - Project is set to CoreN
                        Application to debug is set to Debug/CoreN.elf

/* ------------------------------------------------------------------------------------------------ */

   The linker script is located in ../Workspace/UltraScale.ld
   Adam & Eve stack size is defined at the top of the file.
   The heap (malloc()) is given all the memory left once the code / data / stack has been allocated.

/* ------------------------------------------------------------------------------------------------ */

Demos:

    NOTE: in the freeware version only Demo #3 is provided

    The projects names in the SDK workspace are constructed using this information:

           DEMO_#_TARGET
                |    |
                |    +--------- ZCU102 : ZCU-102  / UltraScale+ A53's
                |
                +-------------- demo #, see below

    Demos with (*) are not pre-packaged but can be created by changing the demo # in the Makefile
    of Demo_10_???, or Demo_10A_????, or Demo_20_???. All demos have been verified.

Demo #3       : Complex demo that shows the operations of some unique features of the Abassi RTOS.
                The operational characteristics of the tasks can be modify through the serial port.
                A thorough description is available on Code-Time Technologies website.
                **** This demo CANNOT use the library re-entrance protection mecanism.
                Must define OS_NEWLIB_REENT=0
                     This demo is flooding the kernel with non-stop service requests.

Demo #8       : This demo is board dependent.
                Typicaly show the use of on-board display(s) or other I2C peripherals.
                It show the use of the I2C driver.

Demo #9       : Small file system shell for FatFS.

Demo #10      : Webserver showing lwIP 1.4.1 with netconn and memory based file system.

Demo #10A     : Webserver showing lwIP 2.0.3 with netconn and memory based file system.

Demo #11  (*) : Webserver showing lwIP 1.4.1 with BSD sockets and memory based file system.

Demo #11A (*) : Webserver showing lwIP 2.0.3 with BSD sockets and memory based file system.

Demo #12  (*) : Webserver showing lwIP 1.4.1 with netconn and FatFS file system.

Demo #12A (*) : Webserver showing lwIP 2.0.3 with netconn and FatFS file system.

Demo #13  (*) : Webserver showing lwIP 1.4.1 with BSD sockets and FatFS file system.

Demo #13A (*) : Webserver showing lwIP 2.0.3 with BSD sockets and FatFS file system.

Demo #14  (*) : Webserver showing lwIP 1.4.1 with netconn and Syscall / FatFS file system.

Demo #14A (*) : Webserver showing lwIP 2.0.3 with netconn and Syscall / FatFS file system.

Demo #15  (*) : Webserver showing lwIP 1.4.1 with BSD sockets and Syscall / FatFS file system.

Demo #15A (*) : Webserver showing lwIP 2.0.3 with BSD sockets and Syscall / FatFS file system.

Demo #16  (*) : Webserver showing lwIP 1.4.1 with netconn and Syscall / FullFat file system.

Demo #16A (*) : Webserver showing lwIP 2.0.3 with netconn and Syscall / FullFat file system.

Demo #17  (*) : Webserver showing lwIP 1.4.1 with BSD sockets and Syscall / FullFat file system.

Demo #17A (*) : Webserver showing lwIP 2.0.3 with BSD sockets and Syscall / FullFat file system.

Demo #18  (*) : Webserver showing lwIP 1.4.1 with netconn and Syscall / ueFat file system.

Demo #18A (*) : Webserver showing lwIP 2.0.3 with netconn and Syscall / ueFat file system.

Demo #19  (*) : Webserver showing lwIP 1.4.1 with BSD sockets and Syscall / ueFat file system.

Demo #19A (*) : Webserver showing lwIP 2.0.3 with BSD sockets and Syscall / ueFat file system.

Demo #20      : Small file system shell for System Calls using FatFS.

Demo #21 (*)  : Small file system shell for System Calls using FullFAT.

Demo #22 (*)  : Small file system shell for System Calls using Ultra Embedded FAT (ueFAT).

Demo #29 (*)  : Small file system shell for System Calls using all 3 file system stacks.
                The file system stacks are FatFS, FullFAT, and Ultra Embedded FAT
                This shows the use of the SysCall_Multi.c file in order to integrate multiple
                mass storage stack/drivers in an application.

Demo #30      : QSPI flash memory demo code

Demo #40      : SPI demo code

Demo #50      : DMA memory transfers demo code

Template      : template makefile to start a project from scratch

     NOTES:
        Demo #3:
        When G_OS_MP_TYPE is set for BMP (value of 4 or 5) these tasks are attached to Core #1:
               HI, RRA and RRB (top 3 on the display)
        All other tasks are allowed to run on any of the 2 cores.

        Refer to Code Time Technologies website for the meaning of the letters on the right of
        display. Configuration commands are not available on uAbassi as none of the controllable
        features offered by mAbassi are supported by uAbassi.

        Demo #10 -> #19:
        When G_OS_MP_TYPE is set for BMP (value of 4 or 5) the tasks created internally by lwIP
        can be forced to run on a specific core by setting LWIP_ABASSI_BMP_CORE_2_USE to the core #ar
        These tasks are:
            - Ethernet I/F
            - tcpip_thread

/* ------------------------------------------------------------------------------------------------ */
/* Overall file system from at this level                                                           */

. --- / --- readme.txt    [me]
      |
      / --- Workspace     SDK Workspace
      |
      / --- inc           Demo include files
      |
      / --- src           target specific demo source code

/* ------------------------------------------------------------------------------------------------ */
/* PROJECTS

     To use mAbassi on other platform than currently supported, refer to the file Platform.txt
     in the directory ../Platform/inc, one level above
     You will have to add new platform definitions in the files Platform.h and HWinfo.h

   - Demos #12 -> #19  require files on the SD/MMC card.
     Make sure to use a Fat32 formatted SD/MMC card and copy all the contents of ../Share/fs on the
     SD/MMC card.  Without these files on the card, the demo will fail as they are the html files
     the demo uses.

   - Verified / library built with  Xilink SDK 2018.2
     If another version of the GCC tool chain is used, it is important in the case of the re-entrant
     library to make sure the compiler library and Abassi library match. In your application
     call ChkNewlib().  Refer to ../Abassi/ChkNewlib.c to see the meaning of the return value.
     DO NOT INCLUDE ChkNewlib.c in your project as it will overload the one in Abassi's library. 

   - All projects rely on 3 makefiles
		The root Makefile is located in the project itself (name Makefile) and it defines the
        the target platform and other set-up.
        The root Makefile includes a makefile named Demo#_GCC.make and this second level of
        makefile contains all the demo # specifics.  The second level makefile then includes
        Common_GCC.make which contains everything common to all demos.
        If a platform does not have a project it's quite easy to create one.
        - Copy and paste (rename) any project with the desired demo.
        - In the project, change in the root makefile the definitions of PLATFORM
          In the project, The recognized platform # are described in ../Platform/inc/Platform.txt
        - If the desired target platform is not one supported by the provided demos, these 2 files
          need to be upgraded to include the new platform:
                ../Platform/inc/Platform.h
                ../Platform/inc/HWinfo.h
          Make sure to go through ../Platform/inc/Platform.txt to correctly define the new platform
        - You'll likely need to upgrade the Demo#_GCC.make and Common_GCC.make too for board specifics

    The makefile in the project defines the following token:

        - BUILD_TYPE         Type of build
                             Set to:
                                 TYPE_SRC   : Use with the RTOS source code
                                 TYPE_EVAL  : Always use with Freeware and Evaluataion package)
                                 TYPE_LIB   : Always use with the Trial / library package
                                 *** MUST BE SET TO TYPE_EVAL
        - LINARO             With GCC, it specifies if the complier chain is Linaro based or not
                             Set to:
                                 YES
                                 NO
        - PERF_MON           If performance monitoring is included.
                             Set to 
                                 YES
                                 NO
                                 *** MUST BE SET TO NO
        - DBG_SHELL          If the debug / monitoring shell is included. Note only demos #3, 10->19
                             are set-up to use the shell. All other demos don;t realy have a use
                             for it.
                             Set to:
                                 YES
                                 NO
                                 *** MUST BE SET TO NO
        - UART_TYPE          Defines how to set-up the UART.  In the demo specific makefile, this
                             token select if polling / mailboxes / circular buffer are used.
                             Set to: 
                                 POLL : polling
                                 MBX  : mailboxes and the # of entries in the mailbox is
                                        set to (OX_MAX_PEND_RQST)/4 in the file Platform.h
                                 #    : Circular buffer (# is the size of the RX & TX buffers
        - DEMO_NMB           Number of the demo
                             If a new project mased on these 3 makefile is created, create a new
                             project specific makefile.  Starting with Demo3_GCC.make would be the
                             simplest approach.
        - PLATFORM           Used to define OS_PLATFORM and platform specifics in the makefiles
                             As the token is used in makefile conditionals, it is case sensitive
                             and "0x" (NOT "0X") and all 8 digits must be sepcified.
                             Set to:
                                 0x00007753 : Ultrascale+ ECU102 A53 processors 
                             If using another board than these, refer to Platform.txt for the
                             numbering and make sure to upgrade both Demo#_???.make & Common_???.make
        - N_CORE             Number of cores (Freeware packages must match the library)
        - LIB_REENT          If using the "C" library rentrance / multi-core protection.
                             set to:
                                  0 : no protection
                                  1 : with protection (all tasks)
                                 -1 : with protection (per task)
                                 *** Freeware MUST SET TO 0
                                     Re-entrant library is built with LIB_REENT == 1, NOT == -1

   - To change the default setting of the drivers, e.g. module clock, refer to the driver user guide
     on Code Time's website.  All configuration of the drivers is done through build option described
     in the user guides.

   - If the application goes in an infinite loop (asm branch to itself), it is likley due to one of
     these:
		- Out of memory (will occur in OS_alloc())
		- Stack overrun (will occur in Abassi())
		- ISR queue overflow (will occur in Abassi())

/* ------------------------------------------------------------------------------------------------ */
/* BUILD OPTION SETTING																				*/

The "C" build options are set in the file ../Platform/inc/AbassiLib.h, with these ones externally
 defined:
		OS_N_INTERRUPTS			1024
		OS_START_STACK			32768


The Assembly build options are the followings:

		OS_FPCR_LOCAL			 1

		OS_SAME_L1_PAGE_TBL		 0
		OS_MMU_EXTERN_DEF		 1
		OS_MMU_ALL_INVALID		 0
		OS_USE_NON_SHARED		 1
		OS_MMU_TBL_2			64
		OS_MMU_TBL_3			64

/* EOF */

