/* ------------------------------------------------------------------------------------------------ */
/* FILE :        readme.txt                                                                         */
/*                                                                                                  */
/* CONTENTS :                                                                                       */
/*               uAbassi SMP RTOS: description for ARM Cortex A53 / XSDK (Free version)             */
/*                                                                                                  */
/*                                                                                                  */
/* Copyright (c) 2017-2019, 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.5 $                                                                                */
/*  $Date: 2019/02/19 16:56:03 $                                                                    */
/*                                                                                                  */
/* ------------------------------------------------------------------------------------------------ */

*** IMPORTATNT ***

   This version uses and was built with a Newlib configured with  multi-thread and multi-core
   protection. SDK''s A53 Nwwlib IS LIKELY NOT compatible with this configuration.

           ******* YOU MUST USE A NEWLIB BUILT WITH __DYNAMIC_REENT__  *******

   The Newlib with rentrance protection used in building uAbassi can be downloaded from
   Code Time web site



   This is uAbassi free version and it supports a limited number of tasks, semaphores and mutexes.
   If the RTOS UART driver is used with ISRs, 2 semaphores are required by the driver.

   Demos are all UART-based and only a RS232 terminal is needed.
   The FPGA image file "design_1wrapper.bit" is located in Workspace/ZCU102-ES2_hw_platform
   It is the default ZCU102 version 2 FPGA image supplied by Xilinx.
   i.e. it's the one used in the "Hello World" project example.
   If the version of the target board is different, replace it by the appropriate one.

     -------------------------------------------------

Quick overview at this level:

   - All RTOS related source code uAbassi.h) is located in the directory ../Abassi, one level above
   - uAbassi & MMU/Cache configuration is in ../Platform/src/uAbassiCfgA53.c
   - The demos source code are located in the folder ../Share/src
   - The demos include files are located in the folder ../Share/inc
   - The SDK workspace is ./Workspace
   - All demo projects are located in individual folders in ./Workspace
   - The drivers are located in the folder ../Drivers

   - The uAbassi libraries are located  in the directory ../Platform/lib, one level above
   - This library is provided according to the target platform:
        for Ultrascale+ A53 
             lib_uAbassi_FREE_R_GCC_ULTRASCALE_A53.a  : 4 cores GCC / with library re-entrance protection

   - For all projects, these definitions must be set:
        OS_PLATFORM     : must be set to 0x00007753 (ZCU-102)
        OS_DEMO         : must be set to a -ve value, except for uDemo to set at 0xDEDE
        OS_N_CORE       : must be set to 4
        OS_NEWLIB_REENT : IGNORED - internally forced to 1
        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
                          available in ../Platform/inc/AbassiLib.h. Setting the proper value of
                          OS_TIME_US will convert all human time to the correct # timer tick.
                          One demo using a different OS_TIME_US setting is Demo #50.

        You can change the multi-processor algorithm (SMP - BMP - packed - non-packed) by defining
        OS_MP_TYPE or by changing it directly in ../Platform/src/uAbassiCfg.c
        You can change the stack size for the Idle tasks by defining OS_START_STACK or by changing
        it directly in ../Platform/src/uAbassiCfg.c

        DO NOT SET any other Abassi/uAbassi/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 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

/* ------------------------------------------------------------------------------------------------ */
/* IMPORTANT NOTES                                                                                  */

   - Verified / library built with SDK version 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 uAbassi library match. In your application
     call ChkNewlib().  Refer to ../Abassi/ChkNewlib.c
     DO NOT INCLUDE ChkNewlib.c in your project as it will overload the one in uAbassi'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 uDemo_GCC.make and this second level of
        makefile contains all demo specifics.  The second level makefile then includes
        Common_GCC.make, which contains everything common to all demos.

        - These are the definitions set in the root makefile
            - BUILD_TYPE     Type of build (Freeware & Evaluation packages must always be set to
                             TYPE_EVAL)
                             set to:
                                 TYPE_SRC   : *** DO NOT USE ***
                                 TYPE_EVAL  : *** DO NOT USE ***
                                 TYPE_FREE  : MUST ALWAYS BE SET TO TYPE_FREE
                                 TYPE_LIB   : *** DO NOT USE ***
                                 TYPE_BM    : *** DO NOT USE ***
            - 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       Must be set to a -ve value, except for uDemo to set at 0xDEDE
            - PLATFORM       Use to define OS_PLATFORM and platform specifics in the makefiles
                             As the token is used in makefile conditionals, it is case sensitive
                             set to:
                                 0x00007020 (ZedBoard)
            - N_CORE         Number of cores - MUST be set to 4
            - LIB_REENT      IGNORED - forced to 1
            - PERF_MON       MUST BE SET TO NO (Performance monitoring isn;t supported by uAbassi)
            - DBG_SHELL      YES / NO : if the debug/monitoring shell is included in the application

/* ------------------------------------------------------------------------------------------------ */
/* 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
        . . . . /uAbassi_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  : Zedboard_bsp_wrapper_hw_platform_0
                 "Bitstream file"     : Zedboard_bsp_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/Zedboard.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.


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

. --- / --- readme.txt    [me]
      |
      / --- Workspace     [SDK Workspace]
      |
      / --- inc           empty
      |
      / --- src           empty

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

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


The Assembly build options are the following:

		OS_VFP_TYPE				32
		OS_SPINLOCK				 1
		OS_ABORT_STACK_SIZE		-2
		OS_FIQ_STACK_SIZE		-2
		OS_IRQ_STACK_SIZE		-2
		OS_SUPER_STACK_SIZE		-2
		OS_UNDEF_STACK_SIZE		-2
		OS_USE_CACHE			 1
		OS_MMU_EXTERN_DEF		 1
		OS_L2_BASE_ADDR			-1
		OS_SAME_L1_PAGE_TBL		 0
		OS_ARM_ERRATA_ALL		 1
		OS_MMU_ALL_INVALID		 0
		OS_L1_CACHE_BP			 1
		OS_L1_CACHE_PF			 1
		OS_L2_CACHE_PF			 1
		OS_CACHE_WRITE_ZERO		 1
		OS_USE_NON_SHARED		 1

/* EOF */

