/* ------------------------------------------------------------------------------------------------ */
/* FILE :        readme.txt                                                                         */
/*                                                                                                  */
/* CONTENTS :                                                                                       */
/*               uAbassi SMP RTOS: description for ARM Cortex A9 / DS-5 (Bare Metal version)        */
/*                                                                                                  */
/*                                                                                                  */
/* Copyright (c) 2014-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.2 $                                                                                */
/*  $Date: 2019/02/19 16:56:05 $                                                                    */
/*                                                                                                  */
/* ------------------------------------------------------------------------------------------------ */

Demos:

	BareMetalA9.c / BareMetalApps.c :
           Demonstrate how to get a Standalone / bare-metal application up and running
           BareMetalA9.c is for uAbassi start and launching the standalone code on each core
           BareMetalApps.c is the code for each code.

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

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/uAbassiCfgA9.c
   - The demos source code are located in the folder ../Share/src
   - The demos include files are located in the folder ../Share/inc
   - The DS-5 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
   - These libraries are provided according to the target platform:
       for the Arria 5 and Cyclone V
             lib_uAbassi_BM_ARMCC_AR5_CY5.a : 2 cores ARMCC / with library re-entrance protection
             lib_uAbassi_BM_GCC_AR5_CY5.a   : 2 cores GCC / with library re-entrance protection
             lib_uAbassi_BM_GCCli_AR5_CY5.a : 2 cores GCC Linaro / with library re-entrance protection
       for the Arria 10
             lib_uAbassi_BM_ARMCC_AR10.a    : 2 cores ARMCC / with library re-entrance protection
             lib_uAbassi_BM_GCC_AR10.a      : 2 cores GCC / with library re-entrance protection
             lib_uAbassi_BM_GCCli_AR10.a    : 2 cores GCC Linaro / with library re-entrance protection
       for the i.MX6
             lib_uAbassi_BM_ARMCC_iMX6_2.a  : 2 cores ARMCC / with library re-entrance protection
             lib_uAbassi_BM_ARMCC_iMX6_4.a  : 4 cores ARMCC / with library re-entrance protection
             lib_uAbassi_BM_GCC_iMX6_2.a    : 2 cores GCC / with library re-entrance protection
             lib_uAbassi_BM_GCC_iMX6_4.a    : 4 cores GCC / with library re-entrance protection
             lib_uAbassi_BM_GCCli_iMX6_2.a  : 2 cores GCC Linaro / with library re-entrance protection
             lib_uAbassi_BM_GCCli_iMX6_4.a  : 4 cores GCC Linaro / with library re-entrance protection

   - For all projects, these definitions must be set:
        OS_PLATFORM     : must be set to 0x0000AAC5 (Cyclone V SocFPGA dev board)
                                         0x0100AAC5 (DE0-Nano / DE10-Nano / Atlas)
                                                     The 3 boards abopve are identical softwarewise
                                         0x0200AAC5 (EBV Socrates)
                                         0x4000AAC5 (Arria V SocFPGA dev board)
                                         0x0000AA10 (Arria 10 SocFPGA dev board)
                                         0x0000FEE6 (i.MX6 Sabrelite)
        OS_DEMO         : must be set to a -ve value, except for BareMetal to set at 0xBABA
        OS_N_CORE       : must be set to 2 (Cyclone V, Arria 5 and Arria 10, i.MX6@2cores)
                          must be set to 4 (i.MX6@4cores)
        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                                                                                  */

   - On the Arria 10, it is VERY IMPORTANT this is done; otherwise u-boot will fail:
     You need to use the proper SD/MMC disk image.  You can get it from Code Time website but using
     the Arria 10 Demo image.  More information about the whys is available from Altera:
             https://www.altera.com/en_US/pdfs/literature/ug/ug-a10-soc-boot.pdf
   - For the i.MX6, the regsiomuxc.h used is the 4 core one (Sabrelite).  When using the 2 core
     demos and the target part is a 2 core one, make sure to change the directory search path in "C"
     for the correct target processor.
   - The DE10-nano is identical from the software point of view to the DE0-nano.
     DE0-nano demos run as is on the DE10-nano

   - Verified / library built with SocEDS version 18.0 / DS5 5.20.0 / ARMCC 5.05u1
     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. 
     This does sot apply to ARMCC.

   - 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 BareMetal_GCC.make or BareMetal_ARMCC.make and
        this second level of makefile contains all demo specifics.  The second level makefile
        then includes Common_GCC.make or Common_ARMCC.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  : *** DO NOT USE ***
                                 TYPE_LIB   : *** DO NOT USE ***
                                 TYPE_BM    : MUST ALWAYS BE SET TO TYPE_BM
            - LINARO         YES / NO : for GCC only it specifies if the complier chain is Linaro
                             based or not
            - 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 BareMetal to set at 0xBABA
            - 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:
                                 0x0000AA10 : Arria 10 SocFPGA dev baord
                                 0x0000AAC5 : Cyclone V SofFGPA dev board
                                 0x0100AAC5 : DE0-nano & DE10-nano
                                 0x0200AAC5 : EBC Socrates
                                 0x4000AAC5 : Arria 5 SofFGPA dev board
            - N_CORE         Number of cores - MUST match the library)
            - 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_CortexA9_DS5/Workspace
       DO NOT check the box "Copy projects into workspace"
       DO NOT check the box "Add project to working sets"
     Click on "Finish"

     To use GCC, the environment path variable must point to a the code sourcery GNU tool-chain
     for the ARM.  This is most likely located in:
      ....\Altera\##.#\embedded\host_tools\mentor\gnu\arm\baremetal\bin

     To build the projects:
     Right click on the project, select "Build Project"

     To run the demo:
     Right click on the project, select "Debug as" and then "Debug Configurations..."
     Expand the "DS-5 Debugger" menu
     Double click on the project to run


     -------------------------------------------------
     The normal start-up sequence for the GCC demos is:

     When connecting to the board, the following should show on the UART:
          U-Boot SPL 2013.01.01 (Feb 05 2014 - 08:46:12)
          BOARD : Altera SOCFPGA Cyclone V Board
          SDRAM: Initializing MMR registers
          SDRAM: Calibrating PHY
          SEQ.C: Preparing to start memory calibration
          SEQ.C: CALIBRATION PASSED
          SDRAM: ECC Enabled

     The Debug window should show:
          Cortex-A9_0 #0 stopped
             = _prestart_+0x..     (could also be "_boot" or "__cs3_reset_generic" or "Reset_Handler")
          Cortex-A9_1 #1 stopped
             = S:0x00000000

     Select Cortex=A9_0 and click on run (green triangle)
     This will show up:
          Cortex-A9_0 #0 stopped on break-point
             = main
             = __cs3_premain+0x..
             = __cs3_start_c_+0x..
             = _prestart_+0x..
          Cortex-A9_1 #1 stopped
             = _prestart_+0x..

     Select Cortex-A9_0 and click on run (green triangle) again and the demo will start.
     All output are sent to the UART.


     -------------------------------------------------
     The normal sequence for the ARM compiler demos is:

     When connecting to the board, the following should show on the UART:
          U-Boot SPL 2013.01.01 (Feb 05 2014 - 08:46:12)
          BOARD : Altera SOCFPGA Cyclone V Board
          SDRAM: Initializing MMR registers
          SDRAM: Calibrating PHY
          SEQ.C: Preparing to start memory calibration
          SEQ.C: CALIBRATION PASSED
          SDRAM: ECC Enabled

     The Debug window should show:
          Cortex-A9_0 #0 stopped
             = Reset_Handler+0x..
             = S:0x00000000
          Cortex-A9_1 #1 stopped

     Select Cortex=A9_0 and click on run (green triangle)
     This will show up:
          Cortex-A9_0 #0 stopped on break-point
             = main
             = S:0x00000000
          Cortex-A9_1 #1 stopped

     Select Cortex-A9_0 and click on run (green triangle) again and the demo will start.
     All output are sent to the UART.


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

. --- / --- readme.txt    [me]
      |
      / --- Workspace     [DS-5 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			8192


The Assembly build options are the following:

		OS_VFP_TYPE				32			(GCC only)
		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 */

