/* ------------------------------------------------------------------------------------------------ */
/* FILE :        readme.txt                                                                         */
/*                                                                                                  */
/* CONTENTS :                                                                                       */
/*               mAbassi SMP RTOS: description for ARM Cortex A9 / DS5 (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.2 $                                                                                */
/*  $Date: 2014/05/03 16:01:48 $                                                                    */
/*                                                                                                  */
/* ------------------------------------------------------------------------------------------------ */


*** 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 DS5 workspace is ./Workspace
   - All demo projects are located in individual directories in ./Workspace
   - The RTOS drivers are located in ../Drivers, one level above

   - These libraries are provided in ../Platform/lib:
       for the Arria 5 and Cyclone V
             lib_mAbassi_EVAL_ARMCC_AR5_CY5.a   : ARMCC mAbassi no re-entrance protection
             lib_mAbassi_EVAL_GCC_AR5_CY5.a     : GCC mAbassi no NEWLIB re-entrance protection
             lib_mAbassi_EVAL_GCCli_AR5_CY5.a   : GCC Linaro mAbassi no NEWLIB re-entrance protection
       for the Arria 10
             lib_mAbassi_EVAL_ARMCC_AR10.a      : ARMCC mAbassi no re-entrance protection
             lib_mAbassi_EVAL_GCC_AR10.a        : GCC mAbassi no NEWLIB re-entrance protection
             lib_mAbassi_EVAL_GCCli_AR10.a      : GCC Linaro mAbassi no NEWLIB re-entrance protection
       for the i.MX6
             lib_mAbassi_EVAL_ARMCC_iMX6_2.a    : 2 cores ARMCC mAbassi no re-entrance protection
             lib_mAbassi_EVAL_ARMCC_iMX6_4.a    : 4 cores ARMCC mAbassi no re-entrance protection
             lib_mAbassi_EVAL_GCC_iMX6_2.a      : 2 cores GCC mAbassi no re-entrance protection
             lib_mAbassi_EVAL_GCC_iMX6_4.a      : 4 cores GCC mAbassi no re-entrance protection
             lib_mAbassi_EVAL_GCCli_iMX6_2.a    : 2 cores GCC Linaro mAbassi no re-entrance protection
             lib_mAbassi_EVAL_GCCli_iMX6_4.a    : 4 cores GCC Linaro mAbassi no 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)
                                                     These 3 boards are identical software-wise
                                         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
        OS_N_CORE       : must be set to 2 (Cyclone V, Arria 5 and Arria 10, i.MX6)
                          must be set to 4 (i.MX6)
        OS_KEIL_REENT   : See OS_NEWLIB_REENT
        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_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, likely from Altera's SocEDS.  This would be 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

   - GCC demos are based on 3 makefile, and the main makefile is located in the related Project
     directory.  This makefile should be easy to upgrade for any needs.

     -------------------------------------------------
     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 breakpoint
             = 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 breakpoint
             = 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.

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

Demos:

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

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

           DEMO_#_SMP_TARGET_A9_TOOL
                |        |       |
                |        |       +----- GCC
                |        |              ARMCC
                |        |
                |        +------------- AR5        : Arria 5 SocFPGA dev board
                |                       AR10       : Arria 10 SocFGPA dev board
                |                       CY5        : Cyclone 5 SocFPGA dev board
                |                       DE0NANOSOC : DE0-Nano / DE10-Nano / Atlas
                |                       SOCRATES   : EBV Socrates
                |                       iMX6       : iMX6 Quad core
                |
                +---------------------- demo #, see below


    AR5:      Arria 5 SoC development kit
                www.altera.com/products/boards_and_kits/dev-kits/altera/kit-arria-v-soc.html
    AR10:     Arria 10 Soc development kit
                altera.com/products/boards_and_kits/dev-kits/altera/arria-10-soc-development-kit.html
    CY5:      Cyclone 5 SoC development kit
                www.altera.com/products/boards_and_kits/dev-kits/altera/kit-cyclone-v-soc.html
    DE0NANO:  Terasic DE0-Nano development board
                www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=139&No=593
              Terasic DE10-Nano development board
                www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=165&No=1046
              Terasic Atlas development board
                www.terasic.com.tw/cgi-bin/page/archive.pl?Language=English&CategoryNo=163&No=941
    SOCRATES: EBV Electronik SOCrates development board
                www.ebv.com/products/product-details/5797/ 
              NOTE: On some revisions of the board, a 10K pull-up must be added between the
                    I2C clock and VCC/3.3V

    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 / OS_KEIL_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     DS-5 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

   - 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

   - 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 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 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. 
     This does not apply to ARMCC and ChkNewlib() is not included in the ARMCC 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 or Demo#_ARMCC.make and this
        second level of makefile contains all the demo # specifics.  The second level makefile
        then includes Common_GCC.make or Common_ARMCC.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
          The recognized platform # are described in ../Platform/inc/Platform.txt
        - Modify debug_nonhosted.ds. Near the bottom of the file you need to load the correct file by
          using the demo # and <Platform> name:
				loadfile "$sdir/Demo_#_SMP_<PLATFORM>_A9_ARMCC.axf" 0x0   (for ARMCC)
				loadfile "$sdir/Demo_#_SMP_<PLATFORM>_A9_GCC.axf" 0x0     (for GCC)
        - In the project rename the launch script and modify it in "Debug as/Debug Configuration"
          in DS5
        - 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 / Demo$_ARMCC.make and Common_GCC.make/
          Common_ARMCC.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 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_ARMCC.make or
                             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:
                                 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
                             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			8192
        OS_KEIL_REENT           library dependent
        OS_NEWLIB_REENT         library dependent


The Assembly build options are the following:

		OS_VFP_TYPE				32			(GCC only)
		OS_RUN_PRIVILEGE		 1
		OS_HANDLE_PSR_Q			 0
		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
        OS_KEIL_REENT            library dependent ARMCC only
        OS_NEWLIB_REENT          library dependent GCC only

/* EOF */
