#  Copyright 2020-2022 NXP
#
#  NXP Confidential. This software is owned or controlled by NXP and may only
#  be used strictly in accordance with the applicable license terms. By
#  expressly accepting such terms or by downloading, installing, activating
#  and/or otherwise using the software, you are agreeing that you have read,
#  and that you agree to comply with and are bound by, such license terms. If
#  you do not agree to be bound by the applicable license terms, then you may
#  not retain, install, activate or otherwise use the software.


1 Introduction
==============
Example application demonstrates configuration of PFE MCAL driver and its integration with other MCAL drivers. It uses Port driver to configure pins and Mcu driver to configure PFE clock.

All files in the example_application project are provided as sample code only. They are not part of the production code deliverables.

1.1 Supported hardware
----------------------
For S32G2 the application supports S32G EVB, which consists of 2 boards:
 1) Platform board: 
    - S32GRV-PLATEVB 700-30081 REV A
      Requires fix – Errata E-PLATGRV-0001
 2) Processor board, there are 2 versions:
    - X-S32G-PROCEVB-S 700-32170 REV X3
      Requires fix – Errata E-S32G-EVB-001
    - X-S32G-PROCEVB-S 700-32170 REV A4
For S32G3 the application supports both EVB and RDB boards:
 1) RDB3 board
    - X-S32G-VNP-RDB3 SCH-53060 REV E1 (only with silicon cut 1.0)
 2) Processor board
    - S32G-PROCEVB3-S SCH-50784 REV A (only with silicon cut 1.1)
1.2 Supported compilers
-----------------------
  - Greenhills
  - GCC
  - Windriver diab

1.3 Dependencies
----------------
  - MCAL for S32G:
    - SW32G_RTD_4.4_4.0.0

1.4 Known issues
----------------
  There are no known issues in this app.

1.5 Functional description
--------------------------
The application configures the hardware, then it sends and receives Ethernet frames on EMAC0 and EMAC1 interfaces. Counters are incremented with each received/transmitted frame, with each Tx confirmation and with each Tx error. Each controller has its set of counters, for example:
  pfeRxCtr = (14, 14)
  pfeTxCtr = (14, 14)
  pfeTxConfCtr = (14, 14)
  pfeTxErrorCtr = (0, 0)

Inbound traffic, in order to be received, must be addressed to interface's MAC address or to broadcast MAC address. Alternatively the controller can be configured to promiscuous mode to receive any traffic.

Outbound traffic consists of invalid IPv4 frames.

EMAC0 is connected to the SGMII (SERDES PCIe) PHY on the processor board. This is the default configuration
EMAC0 is also connected to Ethernet switch sja1105p on platform board, which is connected to ports: 2x BroadReach, RGMII-ADD-2 and RGMII-ADD-3.
To enable this configuration, update the following:
-in the PFE configuration
    change EthCtrlMacLayerSubType for EthCtrlConfig_0 from SERIAL to REDUCED
-in the Mcu configuration:
    change McuGENCTRL1 Source from SERDES_1_XPCS_0_TX to PFEMAC0_TX_DIV_CLK
    change McuCgm2ClockMux4 Source from SERDES_1_XPCS_0_CDR to PFE_MAC_0_EXT_RX_CLK
Refer to chapter [23.7.2.3.1 PFE_MAC_0 clocking overview] in S32G2_RM for more information
If sja1105p switch driver is not integrated to application, then transmission and reception on EMAC0 will not work in this configuration.

EMAC1 is connected to RGMII port on processor board. 

1.5.1 MCAL FCI demo
-------------------
The FCI API is enabled in the provided Tresos configuration project. It can be disabled in 
EthVendorSpecific area. The user can also configure routing table parameters and buffer count.

Now, the example application can be build with the parameter FCI_L2BR_TEST=TRUE. If enabled, the application sets up the 
L2 bridge for the default domain (VLAN 1), adds emac0, emac1, hif0 and hif1 to the bridge domain, and sets the domain 
policies: forward for unicast hit, flood for unicast miss, forward for multicast hit and flood for multicast cast miss.
It is recommended to also add DEBUG=TRUE when using this option.

The example application can also build with the parameter FCI_RTABLE_TEST=TRUE. If enabled, the
Application will register 2 routes and setup a new connection between them.
It is recommended to also add DEBUG=TRUE when using this option.

1.5.2 PFE configuration for PFE to LLCE or LLCE to PFE routing
--------------------------------------------------------------
To use PFE to LLCE routing (Ethernet to CAN) or LLCE to PFE routing (CAN to Ethernet), the HIF channel used by LLCE must be configured using the minihif driver. 
This is done in the source file minihif_hw_conf.c. The hardware configurations will include:
 - initialize PFE HW used by LLCE
 - configure buffer descriptors (BD) for minihif with BD access permission is FALSE
 - configure the EMACs
 - configure packet steering and filtering

To enable PFE-LLCE hardware configuration, the application needs to build with the parameter CONFIG_MINIHIF=TRUE. Besides, the HIF channel used by LLCE can be 
selected with parameter CONFIG_MINIHIF_HW=<hif_instance> (The valid values for <hif_instance> are HIF1/HIF2/HIF3). The HIF interface selected for minihif should 
NOT be configured in a controller in tresos.

1.5.3 Master-slave demo
-----------------------
The example application demonstrates Master-slave scenario run in one board.
To run and debug with Master and slave application, user needs to do the following steps.
  - Step 1: Configure for parameters in the Makefile and project_parameters.mk
    + In project_parameters.mk: ensure that all paths and package names are correct in user's environment
    + In Makefile: At the beginning of this file, there are some options to configure features used in the application. User needs to configure appropriate value for those options (see section 3.2 for more detail about meaning of those options)
    For example, if user wants to switch to other hardware platform, user can change the value of HW=S32G2, S32G3 or S32G3_REV1_1
  - Step 2: Build the master/slave application
    + Open Cygwin or any cmd window and direct to the application's directory, for example: cd "<user_path>\example_application"
    + To build master application:
      + Configure SLAVE_DRIVER ?= FALSE in Makefile
      + Enter the following commands on terminal
        make clean_all (To clean the built output folder and source generated folder)
        make generate (To generate the sources and headers)
        make build (To compile all related files and create the binary file (.elf))
    + To build slave application:
      + Configure SLAVE_DRIVER ?= TRUE in Makefile
      + Do the same commands with master application
    After step 2, without any errors, user will have main.elf and slave_app.elf (or their G3 versions)
  - Step 3: Run and debug the application with Lauterbach TRACE32
    + Open t32marm.exe (in TRACE32 directory: <T32_dir>\bin\windows or <T32_dir>bin\windows64)
    + On the Menu bar, select File -> Run Script
    + Open "<user_path>\example_application" and choose script to run:
      + 'run_main.cmm' (or 'run_main_G3.cmm' for G3 version) is used to run Master application 
      + 'run_slave_app.cmm' (or 'run_slave_app_G3.cmm' for G3 version) is used to run Master-slave application
    + Once the program is loaded and run, users could pause by pressing Break and use the following commands to switch to other Master or Slave application
      SYStem.CPU S32G274A-M7-1
      SYS.Attach
      Data.LOAD.Elf <user_path>\example_application\output_slave\slave_app.elf /noregister /NoCODE

    Note 1: M7-0 core is used for Master and M7-1 core is used for slave
    Note 2: Both applications will transmit frames on both EMAC0 and EMAC1. If a cable is plugged between EMAC0 and EMAC1, the RX counters will show twice the number of transmitted frames
    Note 3: Use 'go main' to open the debug windows, use 'list <function name>' to open the window with the function user want to debug

2 Configuration
===============
Application contains 2 tresos configuration projects MasterProject and SlaveProject for G2 device and MasterProject_G3 and SlaveProject_G3 for G3 device. 
Either it can be imported to Tresos and configuration can be generated from there, or it can be generated using makefile, command "make generate". 
To generate the slave project, use "make generate SLAVE_DRIVER=TRUE"
Note that using makefile requires prior configuration of paths, see chapter 3.

3 Build
=======
Application can be built using makefile. Before the makefile is run, paths need to be configured: either modify file project_parameters.mk or provide the paths on command line.

3.1 Make commands
-----------------
  - To build the application with default options and GCC compiler:
    make
  - To clean the build:
    make clean
  - To clean the build and generated configuration:
    make clean_all
Note: add SLAVE_DRIVER=TRUE to the make command to build or clean the slave app

3.2 Options for the make command
--------------------------------
  - To select target hardware platform:
    HW=S32G2 (default)
    HW=S32G3
    HW=S32G3_REV1_1
Note: The HW=S32G3_REV1_1 will only change the configuration due to the difference between RDB3 (which uses silicon 1.0) and EVB3 (which uses silicon 1.1) boards
  - To build in debug mode with debug log for PFE driver:
    DEBUG=TRUE
  - To select compiler
    COMPILER=GCC (default)
    COMPILER=GHS
    COMPILER=DIAB
  - Connectivity options:
    USE_SJA1105P_DRIVER=TRUE USE_SERDES_DRIVER=FALSE
        These options are required to be able to TX/RX on MAC0 via sja1105p.
        The switch driver must be integrated and PFE/Mcu configuration updated in tresos
    LOOPBACK_TEST=TRUE
        This option can be be used to RX frames on MAC1 without any cable
        Configuration parameter EthEmacLoopEn must be set for both controllers in tresos
        Both MAC0 and MAC1 will receive their own frames back.
    FCI_L2BR_TEST=TRUE
        This option can be used to enable FCI L2 bridge demo, see section 1.4.1
    FCI_RTABLE_TEST=TRUE
        This option can be used to enable FCI routing table demo, see section 1.4.1
  - To configure PFE hardware to be used by LLCE
    CONFIG_MINIHIF=TRUE
        This option can be used to configure the PFE hardware to be used by LLCE, see section 1.4.2
    CONFIG_MINIHIF_HW=HIF1 (HIF2/HIF3)
        This option can be used to select HIF channel used by LLCE (default is HIF3), see section 1.4.2
  - To generate and build the slave app:
    SLAVE_DRIVER=TRUE
  - Text statistics option:
    TEXT_STATS=FALSE (default)
    TEXT_STATS=TRUE allow to print miscellaneous statistics for PFE (only when DEBUG=TRUE also !)
  - To use serdes drivers and RTD's:
    USE_SERDES_DRIVER=TRUE
    USE_RTD_SERDES_DRIVER=TRUE
  - To configurate the verbosity level:
    VERBOSITY_LEVEL=8 (default)
  - To disable the S32G2 ordered class writes switch in drivers
    G2_NO_ORDERED_CLASS_WRITES=TRUE
  - To enable or disable the setting of many initiation functions
    CONFIGURE_SOC=TRUE
  - To enable or disable user mode support
    USER_MODE=TRUE
    Note: The user needs to turn on each module's user_mode_support=true and re-generate the sources
  - Configure GPT channel to use for TM Stub and switch tasks
    SWITCH_TASK_GPT_CHANNEL_CFG=0 (default)
    TM_STUB_GPT_CHANNEL_CFG=1     (default)

4 Running the application
=========================
Scripts (CMM_FILE) for Lauterbach debugger (TRACE32 for ARM) is provided
run_main.cmm          run standalone app for G2
run_main_G3.cmm       run standalone app for G3
run_slave_app.cmm     run master/slave app for G2
run_slave_app_G3.cmm  run master/slave app for G3


4.1 Steps for running the application
-------------------------------------
 1) Connect debugger
 2) Power-on the EVB, to ensure reliable connection on switch ports, specific power-on sequence is required to workaround a known issue with transceiver connection on EVB:
    - Make sure the EVB is off for at least 30 s.
    - Power on the platform board only
    - Power on the processor board
 3) Open TRACE32 for ARM windows, run script with command: cd.do EXAMPLE_APPLICATION_PATH/CMM_FILE
 4) Hit Run button
 5) The application is running
    - Frame counters are displayed, including counters from switch (if used).
    - If the application was built with DEBUG=TRUE, debug messages will be displayed.
