NXP S32G BSP


1. About this document
======================
This document describes the common and non-hardware specific information.
Please refer to README.hardware for hardware specific information.

Dependencies
------------
This layer depends on the oe-core version supplied with linux-yocto kernel.


Maintenance
-----------
This layer is maintained by Wind River Systems, Inc.
Contact <support@windriver.com> or your support representative for more
information on submitting changes.

Building the nxp-s32g layer
---------------------------
This layer should be added to bblayers.conf. This is done automatically
when using the Wind River setup.sh wrapper.

License
-------
Copyright (C) 2018-2020 Wind River Systems, Inc.

Source code included in the tree for individual recipes is under the LICENSE
stated in the associated recipe (.bb file) unless otherwise stated.

The metadata is under the following license unless otherwise stated.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 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.

2. BSP Kernel and Distros
=========================

The following table summarizes the valid Wind River Linux distros for this BSP.
'Y' in each content cell stands for supported; 'N' stands for not supported:

  +--------------+-------------+-------------+-------------+
  | valid/distro |   wrlinux   | wrlinux-cgl | wrlinux-ovp |
  +--------------+-------------+-------------+-------------+
  |    valid     |      Y      |      N      |      N      |
  +--------------+-------------+-------------+-------------+

For the supported kernel type for this BSP, please check the TARGET_SUPPORTED_KTYPES
by running 'bitbake -e virtual/kernel | grep "^TARGET_SUPPORTED_KTYPES="'.

Note: The preempt-rt ktype is available for this BSP/Machine at this time.


3. Board Specific Patches
=========================

To get a list of patches applied to the kernel specific to this BSP along with
patch descriptions use git-whatchanged on the default kernel. For example:

	%> cd tmp-glibc/work-shared/<bsp_name>/kernel-source
	%> git whatchanged <kernel_version>/standard/base..<kernel_version>/standard/<bsp_name>


4. Boot Instructions
====================

The typical u-boot settings apply to these boards. You will need to use
setenv, printenv and saveenv, to configure, display and store respectively
your network configuration details and kernel command line. In order to
TFTP a kernel, you need at a minimum to set the following:

	- ipaddr
	- gatewayip
	- netmask
	- serverip
	- loadaddr
	- dtbfile
	- dtbaddr
	- ethaddr
	- eth1addr

Your board may ship with the values for the MAC address of
the Ethernet interfaces set to the defaults compiled into the
u-boot image.  You should set the ethaddr, eth1addr and so on
as per the manufacturer assigned values, usually indicated with
a sticker on the board.

Target specifics are usually set in the "bootargs" variable, and the
kernel image is set in the "bootfile" variable. Don't forget that if you
want these values to be available after a power cycle you will need to run
the saveenv command.

Typically convenience macros exist that will create a complete bootargs
command line for the kernel based on variables that contain individual
settings.  Since these macros exist as env variables themselves, they
may or may not be present depending on who installed and configured
u-boot for the board.

The console device for the board is ttyLF0 at 115200 baud. For the DTB
address, 0x8FE00000  was used with success by Wind River. The load address
must be high enough to not interfere with kernel decompression. A value
of 0x8A080000 was used with success for all kernels tested by Wind River.

4.1 NFS Root File System
------------------------

Example settings for the monitor (u-boot) are shown below:

nfsboot=setenv bootargs root=/dev/nfs rw nfsroot=$serverip:$rootpath \
ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname:$netdev:off \
console=$consoledev,$baudrate $othbootargs;tftp $loadaddr $bootfile; \
tftp $fdtaddr $fdtfile;booti $loadaddr - $fdtaddr
ethaddr=00:04:9F:02:00:FD
eth1addr=00:04:9F:02:01:FD
eth2addr=00:04:9F:02:02:FD
loadaddr=0x8A080000
fdtaddr=0x8FE00000
gatewayip=192.168.1.1
netmask=255.255.255.0
ipaddr=192.168.1.100
serverip=192.168.1.2
netdev=eth0
bootfile=Image
fdtfile=<fdt-file-name>
rootpath=/tftpboot/rootfs
consoledev=ttyLF0
baudrate=115200

The fdt-file-name includes the following dtbs:
	s32g2xxa-evb.dtb
	s32g274a-rdb2.dtb
	s32g3xxa-evb.dtb
	s32g399a-rdb3.dtb
Please use the right one for different board.

Note:
By default, in u-boot eth0 is occupied by PFE mode. When in non-PFE mode
in order to switch eth0 to the GMAC by explicitly disabling and enabling
the GMAC driver. Run below commands in u-boot:

# s32ccgmac disable
# s32ccgmac enable
# setenv ethact eth_eqos

4.2 Boot Devices
----------------

For S32G platforms, there are 3 boot devices as following:
    SD, eMMC, QSPI.

If users want to use these devices to boot, the DIP switches on S32G boards
should be configured correctly. And the following are the DIP switches setting
for these 3 boot devies:

For S32G2 EVB/S32G3 EVB:

                eMMC            SD              QSPI
    -------------------------------------------------------
    J50         1 x x           x x 3           x x 3
    -------------------------------------------------------
    SW6         6,7 on          7 on            all off
    -------------------------------------------------------
    SW7
    SW8         all off         all off         all off
    SW9
    -------------------------------------------------------
    SW14        1 on, 2 off     1 on, 2 off     1 on, 2 off
    -------------------------------------------------------
    SW15        1,2 off         1,2 off         1,2 off

    the above "x" means connected, so "1 x x" means pin1 is unused, pin2 and
    pin3 are connected.

For S32G2 RDB2/S32G3 RDB3:

                eMMC            SD              QSPI
    -------------------------------------------------------
    SW3         off             on              off
    -------------------------------------------------------
    SW4         6,7 on          7 on            all off
    -------------------------------------------------------
    SW5
    SW6         all off         all off         all off
    SW7
    -------------------------------------------------------
    SW9         1,2 off         1,2 off         1,2 off
    -------------------------------------------------------
    SW10        1 on, 2 off     1 on, 2 off     1 on, 2 off

The rest of the switches and jumpers are set to default position.

4.3 QSPI Flash Boot
-------------------

Now the QSPI flash boot supported has been added for S32G platforms.
Then take S32G399ARDB3 as example, users can follow the below steps
to boot the board using QSPI atf image:

  0. build the nxp-s32g bsp as normal, then the required QSPI atf
     images(with a _qspi suffix), will be built and deployed along
     with SD WIC images
  1. boot the board with SD WIC image as normal
  2. copy the required QSPI atf image to a proper location of the
     running system by network or other way
  3. burn the QSPI atf image into QSPI flash

     firstly, get the flash partitions like:
        root@nxp-s32g:~# cat /proc/mtd
        dev:    size   erasesize  name
        mtd0: 04000000 00010000 "Flash-Image"
        mtd1: 001e0000 00010000 "FIP"
        mtd2: 00010000 00010000 "U-Boot-Env"
        mtd3: 00e00000 00010000 "Kernel"
        mtd4: 00100000 00010000 "DTB"
        mtd5: 01f10000 00010000 "Rootfs"
        mtd6: 01000000 00010000 "PFE-Firmware"
     and the mtd1 is the location for atf image. So using command:
        flashcp -v atf-s32g399ardb3_qspi.s32 /dev/mtd1
     to burn the QSPI atf image into the mtd1 partition of the flash. The
     output messages should like:
        root@nxp-s32g:~# flashcp -v atf-s32g399ardb3_qspi.s32 /dev/mtd1
        Erasing blocks: 23/23 (100%)
        Writing data: 1452k/1452k (100%)
        Verifying data: 1452k/1452k (100%)
  4. power down the board and change the related DIP switches to QSPI boot:
        SW3: off
        SW4: all off
        other DIP switches keep same as SD boot.
  5. then power up the board, there should be boot messages as following:
        NOTICE:  Reset status: Power-On Reset
        NOTICE:  BL2: v2.5(release):bsp35.0-2.5-10-ge3ce79a4c
        NOTICE:  BL2: Built : 13:21:28, Nov 29 2022
        NOTICE:  BL2: Booting BL31

        U-Boot 2020.04+gf30287c440 (Nov 29 2022 - 16:57:39 +0000)

        CPU:   NXP S32G399A rev. 1.0
        Model: NXP S32G399A-RDB3
        DRAM:  3.5 GiB
        Ignore unsupported SCMI protocol 19
        MMC:   FSL_SDHC: 0
        Loading Environment from SPI Flash... SF: Detected mx25uw51245g with page size 256 Bytes, erase size 64 KiB, total 64 MiB
        OK
        ......

The "Loading Environment from SPI Flash..." line indicates that the boot
device is QSPI flash as expected.

For other S32G boards, please change the QSPI atf image name and
jumpers/DIP switches accordingly.

For SD WIC images, please refer to the following Section "5. Creating
Partitioned Images(WIC)", there are detail information about how to use
or configure SD WIC images to boot.

NOTICE:
    Currently, QSPI flash boot is only supported by S32G platforms and with
    secure boot disabled, because non-S32G platforms and secure boot are only
    supported by SD boot. And due to the current QSPI flash size(64MB)
    limitation on current S32G boards, there are only QSPI atf image built, so
    users need to use NFS or other way to load kernel image/dtb, etc. to fully
    boot up the board to use. Moreover, for S32G RDB2/RDB3 boards, due to the
    SW3 DIP switch is off when use QSPI boot, so only the eMMC device can be
    seen and accessed.
    And for detail informations of the boot description, please refer to the
    section:
        "4 How to boot"
    in SDK user manual "S32Gx_LinuxBSP_36.0_User_Manual.pdf", the S32Gx is
    S32G2 or S32G3 accordingly.

5. Creating Partitioned Images(WIC)
===================================

User can use the OpenEmbedded Image Creator, wic, to create the properly
partitioned image on a SD card. The wic command
generates partitioned images from existing OpenEmbedded build artifacts.
User can refer to the below URL to get more WIC details:

https://docs.yoctoproject.org/singleindex.html#creating-partitioned-images-using-wic

This BSP supports disk images for SD card.
After build the project, user will get a WIC image under the directory
tmp-glibc/deploy/images/<bsp name>/ ,such as:

tmp-glibc/deploy/images/nxp-s32g/wrlinux-image-<rootfs_type>-nxp-s32g-<board>.wic

Then user can write the output image to a SD card:

5.1 Burn images to SD card
--------------------------

To burn WIC image to SD card, user only need to execute the below command:
  # dd if=<wic-image-name> of=/dev/your_sd_dev

The above wic-image-name includes:
  wrlinux-image-std-nxp-s32g-evb.wic  for S32G274A-EVB
  wrlinux-image-std-nxp-s32g-rdb2.wic for S32G274A-RDB2
  wrlinux-image-std-nxp-s32g-evb3.wic for S32G399A-EVB
  wrlinux-image-std-nxp-s32g-rdb3.wic for S32G399A-RDB3

Please use the right one for different board.

5.2 Set uboot env
-----------------

Board can boot automatically by set the below uboot environment variables:

=> setenv bootfile Image; setenv fdtfile <fdt-file-name>; setenv loadaddr 0x8A080000; setenv fdtaddr 0x8FE00000;

=> setenv bootargs console=ttyLF0,115200n8 root=/dev/mmcblk0p2 rw

=> setenv bootcmd 'fatload mmc 0:1 $loadaddr $bootfile; fatload mmc 0:1 $fdtaddr $fdtfile; booti $loadaddr - $fdtaddr'

=> saveenv; run bootcmd;

The above fdt-file-name includes s32g2xxa-evb.dtb, s32g274a-rdb2.dtb,
s32g3xxa-evb.dtb and s32g399a-rdb3.dtb, please use the right fdt file for
different board.

Note:
Because PFE and Ethernet GMAC ports are mutually exclusive, in order to enable
PFE or Ethernet GMAC ports on WIC image need to run u-boot commands first
before "run bootcmd":

To use Ethernet GMAC ports:
=> s32ccgmac disable;s32ccgmac enable;setenv ethact eth_eqos;

To use PFE ports:
=> pfeng stop

NOTICE:
    The SD WIC images can be burnt into SD or eMMC devices to boot the S32G
    boards, and please refer to section
        "4 How to boot"
    in SDK user manual "S32Gx_LinuxBSP_36.0_User_Manual.pdf"(S32Gx is S32G2
    or S32G3 accordingly), to get the detail boot device information.

6. Features
===========

6.1 FLEXCAN
-----------

Detail verification commands as below:

	# ip link set can0 up type can bitrate 800000 dbitrate 8000000 fd on
	# ip link set can1 up type can bitrate 800000 dbitrate 8000000 fd on
	# candump can0 &
	# cansend can1 5A1#11.22.33.44.55.66.77.88
	# ip -d -s link show can0
	# ip -d -s link show can1

If can0 dumps data from can1, FLEXCAN feature works fine.

Note:
For S32G274A-EVB, can0 is the J79 on the S32G-PROCEVB-S board, can1 & can2 are the J19 & J20
on the S32GRV-PLATEVB board.
For S32G274A-RDB2, can0 & can1 are on the J6 on the S32G-VNP-RDB2 board and validated,
can 2 & can3 are no external interfaces and no validation.

6.2 HSE
-------

The NXP HSE (Hardware Security Engine) is a security subsystem aimed at running
relevant security functions for applications with stringent confidentiality and
authenticity requirements. This chapter describes the supported HSE features for
the S32G274A and S32G399A boards. Detailed information can refer to "HSE Reference
Manual".

HSE is a component of S32G274A/S32G399A SOCs. It must be installed with the
firmware to use. HSE firmware is not shipped with SDK. It is released through
NXP's Flexera, customers have to contact NXP to get the access to Flexera.

6.2.1 HSE firmware
------------------

Before to use the HSE, HSE firmware must be installed and the key catalogs must
be formatted.

If you get permission to use HSE, you can get packages "HSE_FW_S32G2_0_1_0_5.exe"
and "HSE_FW_DEMOAPP_S32G2_0_1_0_5.exe" for S32G274A, "HSE_FW_S32G3_0_2_16_1"
and "HSE_DEMOAPP_S32G3_0_2_16_1" for S32G399A from NXP's official website. you
can find the HSE firmware pink images and the related interface directory from
the related HSE_FW_S32Gx_xxx.exe. The interface directory will be used when
compiling the HSE linux demos as "6.2.3 HSE linux" descriped.

6.2.2 HSE Demo
--------------

The demo application is provided separately and contains details on how to
provision HSE FW on virgin devices and demonstrates common use cases of its
security features.

The HSE Demo is from the package "HSE_FW_DEMOAPP_S32Gx_xxx.exe" of NXP's
official website.

Frist step in installing the HSE FW on a device is to generate the blob image,
the blob image is a binary image which defines the layout of external flash memory.
Contains all images used by BootRom/HSE FW to boot and configure the system at start-up.

Below steps is an example about how to verify the HSE function on M7 cores,
detailed information can refer to the document of "HSE_FW_DEMOAPP_S32Gx_xxx_ReadMe.pdf"

In the following steps, take S32G274A SOC as example:
1) Generate the blob image using scripts\blob.py script:

%> set PLATFORM=s32g2xx
%> cd demo_security_installer\scripts
%> python3 blob.py -o new -j json/s32g2xx_new_blob.json -b images/blob_s32g2xx_sd.bin -i sd

2) Flashing the blob image:

%> dd if=blob_s32g2xx_sd.bin of=/dev/your_sd_dev

3) Boot target from SD:

There will be a display below on the serial to confirm HSE is up and running.

	HSE FW Version: 0.1.0_1.0.5
	HSE FW up and running! Status:
	      HSE_STATUS_RNG_INIT_OK
	      HSE_STATUS_INIT_OK
	      HSE_STATUS_CUST_SUPER_USER

NOTICE:
	the script uses rev2 version HSE firmware to create the new blob
	image by dedault, if user's board is rev1 version, please modify the
		json/s32g2xx_new_blob.json
	file to be compatible with the HSE version.

6.2.3 HSE linux
---------------

For linux, there have a demo to verify HSE and it provides PKCS#11 functionality.
The steps are as following:

 1. Build project with HSE built-in into WIC image

    If users want to use HSE feature in linux, please specify the following
    variables, like the following:

        HSE_LOCAL_FIRMWARE_DIR = "/path/to/hse/firmware/for/s32g/boards"
        HSE_FW_VERSION_S32G2 = "firmware-version-for-s32g2"
        HSE_FW_VERSION_S32G3 = "firmware-version-for-s32g3"
        HSE_FW_NAME_S32G2 = "firmware-name-for-s32g2"
        HSE_FW_NAME_S32G3 = "firmware-name-for-s32g3"

    and
        IMAGE_INSTALL += "pkcs11-hse pkcs11-hse-examples opensc"

    in the project <build-dir>/conf/local.conf.

    In detail, The HSE_LOCAL_FIRMWARE_DIR is the top directory for HSE
    firmwares location, the HSE_FW_<VERSION, NAME>_S32G2, and
    HSE_FW_<VERSION, NAME>_S32G3 are firmware version and real firmware
    name for S32G2 and S32G3 respectively.

    And in acctually, the HSE_FW_VERSION_<S32G2, S32G3> are subdirectories of
    HSE_LOCAL_FIRMWARE_DIR. And in this subdirectory, there should have
    firmware interface directory and firmware binary. Because the interface
    directory includes header files, which are needed when compiling pkcs11-hse
    demos, and they are matched with the firmware binary with same version,
    so they should be under the HSE_FW_VERSION_<S32G2, S32G3> subdirectoy
    together. Users can get the interface directory and firmware binary from
    HSE_FW_S32Gx_xxx.exe.

    By setting all the above HSE related variables, users can choose different
    HSE firmware versions to use. The current default version for S32G2 is
    "0.1.0.5" and for S32G3 is "0.2.16.1".

    Take the following HSE firmware directory layout as example:

        xxx/firmwares/hse
        ├── 0.1.0.5
        │   ├── interface
        │   └── rev2.0_s32g2xx_xxx_1.0.5_xxx.bin.pink
        └── 0.2.16.1
            ├── interface
            └── rev1.0_s32g3xx_xxx_2.16.1_xxx.bin.pink

    As shown above, the "interface" and firmware binary *.bin.pink file are
    put together under firmware version subdirectory. And the HSE variables
    should be:
        HSE_LOCAL_FIRMWARE_DIR = "xxx/firmwares/hse"
        HSE_FW_VERSION_S32G2 = "0.1.0.5"
        HSE_FW_VERSION_S32G3 = "0.2.16.1"
        HSE_FW_NAME_S32G2 = "rev2.0_s32g2xx_xxx_1.0.5_xxx.bin.pink"
        HSE_FW_NAME_S32G3 = "rev1.0_s32g3xx_xxx_2.16.1_xxx.bin.pink"
        IMAGE_INSTALL += "pkcs11-hse pkcs11-hse-examples opensc"

    in project conf/local.conf.

    Then build the project as normal:

	bitbake wrlinux-image-std

    after build finish, HSE firmwares will be put into the related WIC images.

 2. Initialize HSE firmware and format key stores

    After step1, using the SD card to boot the board, and when linux system
    starts up, using the following command to format HSE key stores:

	 hse-secboot -f -d /dev/mmcblk0

    If succeed, it should shows:
	[INFO]hse-uio 40210000.mu0b: device hse-uio open
	Formatting HSE key catalog
	hse: device initialized, status 0x0920
	[INFO] Retrieving IVT from device /dev/mmcblk0
	[INFO] Enabling MUs
	[INFO] Formatting NVM and RAM key catalogs
	[INFO] Retrieving SYSIMG size
	[INFO] Publishing SYSIMG
	[INFO] Writing SYSIMG to /dev/mmcblk0
	hse-uio 40210000.mu0b: device hse-uio released

 3. Run the HSE & PKCS#11 demo

    After step2, run the following command:

	pkcs-keyop /usr/lib64/libpkcs-hse.so.1.0

    If succeed, the messages should like:

	root@nxp-s32g:~# pkcs-keyop /usr/lib64/libpkcs-hse.so.1.0 
	hse-uio 40210000.mu0b: device hse-uio open
	hse: device initialized, status 0x0b20

	1 slots available

	Using token:
	Manufacturer......: NXP-Semiconductors
	Description.......: NXP-HSE-Slot
	Token label.......: NXP-HSE-Token

	Keys available: 0

	Key pair #1 stored
	Key pair #2 stored

	Keys available: 2

	Key removed
	hse-uio 40210000.mu0b: device hse-uio released

NOTICE:

    Please make sure that the interface directory and firmware binary file are
    in same version and be put together under HSE_FW_VERSION_<S32G2, S32G3>
    subdirectory, or else, there may be unexpected issues in build or runtime.

    The linux HSE & PKCS#11 demo supports all S32G274A and S32G399A boards now.


6.3 PFE
-------

The NXP PFE (Packet Forwarding Engine) offloads the processing of Ethernet packets
from the host cores, yielding higher performance and lower power than pure software
processing can achieve.

PFE is a component of S32G274A and S32G399A SOCs. It must be installed with the
firmware to use. PFE firmware is not shipped with SDK, customers have to contact
NXP to get permission and download the PFE firmware.

6.3.1 PFE firmware
------------------

PFE is a firmware-based module. Load the firmware before using PFE.
The firmwares name are "s32g_pfe_class.fw" and "s32g_pfe_util.fw" with
version 1.6.0, which have to be downloaded from NXP Software.

6.3.2 Steps to verify
---------------------

1. Add the "pfe" package to the system through including the
following line in your local.conf:

    # Install pfe in rootfs
    IMAGE_INSTALL:append:nxp-s32g = " pfe"

    # Install pfe in initramfs, this is required when initramfs is used,
    # for example, when feature/ostree is enabled.
    PACKAGE_INSTALL:append:nxp-s32g = " pfe"

    # Set firmware dir
    PFE_LOCAL_FIRMWARE_DIR = "<The firmwares fully directory path, eg: lib/firmware/>"

    The variable PFE_LOCAL_FIRMWARE_DIR indicates the location where can
    get the firmwares s32g_pfe_class.fw and s32g_pfe_util.fw.
    And after setting the above variables, the firmwares can be installed
    into WIC image's first boot partition automatically when build WIC image.

2. Built and install them:

	# bitbake wrlinux-image-<small/std>

As PFE driver is a kernel module now, so it should not be used to NFS boot
port. Please refer to the document "S32G Linux PFE Driver User’s Manual" for
more information.

About the detailed pfe port map information can refer to the chapter "Ethernet
Hardware Support on S32G2" and "Ethernet Hardware Support on S32G3" of the
documents of Linux BSP 36.0 User Manual for S32G2 and S32G3 platforms.

Note:

1. For S32G274A-RDB2 and S32G399A-RDB3 boards, if using NFS to verify the PFE
feature, you should first switch eth to GMAC in u-boot, please refer to above
chapter "4.1 NFS Root File System" to switch eth to GMAC.

2. For S32G274A-EVB/S32G399A-EVB boards, the connection over the SJA1105
automotive switch requires firmware to be preloaded to the switch on every
reboot:
	=> sja probe 5:0
	=> sja speed -,-,-,1G,1G 5:0

3. Same as NXP SDK, the ports connected with "SJA1105Q" or "SJA1110A" are not
stable, so they maybe don't work sometimes.

6.3.3 Known issue
-----------------

On S32G274A-EVB/S32G399A-EVB boards, there have an known issue that the pfe1
phy can't work. Because the NXP SDK changed the pfe1 to sgmii mode, then pfe1
will use an AQR107 phy, but when the pfe1 up to work, the RX count of pfe1 is
allways 0, so the pfe1 port can not get any packets from network. And this
issue can be reproduced on SDK pre-built image.

We have submit the issue to NXP to track the progress, and the ticket url
is:
  https://community.nxp.com/t5/Wind-River-S32G-Support/PFE-driver-update-in-BSP33-RC8/m-p/1488518/highlight/false#M182

This issue will be fixed later.

6.4 LLCE
--------

NXP LLCE (Low Latency Communication Engine) is an autonomous accelerator
designed to offload communication tasks on the CAN, LIN and Flexray
Protocols. It is a self-contained module, separate from the application
cores that would run applications (host cores). For now, LLCE CAN has
been supported, LIN and Flexray are not, same as SDK.

LLCE is a component of S32G274A and S32G399A SOCs. It must be installed with
the firmwares to use. LLCE firmwares are not shipped with SDK. It is released
through NXP's Flexera, customers have to contact NXP to get the access to
Flexera.

6.4.1 LLCE firmwares
--------------------

LLCE is a firmware-based module. Load the firmwares before using it.
There are 4 LLCE firmwares:

	dte.bin
	frpe.bin
	ppe_tx.bin
	ppe_rx.bin

with version 1.0.6 to be downloaded from NXP Software.

6.4.2 LLCE CAN verify steps
---------------------------

If users want to verify LLCE CAN feature, please add the following lines in
<build-dir>/conf/local.conf of wrlinux project:

	WRL_RECIPES:wr-nxp-s32g += "llce"
	IMAGE_INSTALL:append:nxp-s32g = " llce"
	LLCE_LOCAL_FIRMWARE_DIR = "<path-to-llce-firmwares-for-s32g2-boards>"
	LLCE_LOCAL_FIRMWARE_DIR_S32G3 = "<path-to-llce-firmwares-for-s32g3-boards>"

	the variable LLCE_LOCAL_FIRMWARE_DIR indecates the firmwares(dte.bin,
	frpe.bin, ppe_tx.bin and ppe_rx.bin) location.

then build the project as usual. Boot up the board with the new built WIC
image, make sure that the test llcecan ports are connected. As an example,
using llcecan0 and llcecan14 to verify. steps as following:

  1. configure llcecan0 and llcecan14 interfaces

	ip link set up llcecan0 type can bitrate 500000 dbitrate 5000000 fd on
	ip link set up llcecan14 type can bitrate 500000 dbitrate 5000000 fd on

  2. capture can messages

	candump any,0:0,#FFFFFFFF > llce_can.log &

  3. send a packet using llcecan14

	cansend llcecan14 15575555##300112233445566778899aabbcceedd112233

  4. verify the capture output

	cat llce_can.log

  If succeed, it should output like:
	root@nxp-s32g:~# cat llce_can.log
	  llcecan0  15575555  [20]  00 11 22 33 44 55 66 77 88 99 AA BB CC EE DD 11 22 33 00 00
	  llcecan14  15575555  [20]  00 11 22 33 44 55 66 77 88 99 AA BB CC EE DD 11 22 33 00 00

6.5 ATF
-------

The ARM Trusted Firmware (ATF, or TF-A) is a software component of
the linux BSP with a double role as a bootloader and Secure Monitor.
As a bootloader, it runs before U-Boot on the A53 boot core and takes
over some of the core and SoC initializations such as clocks or MC_ME
partitions (mostly for those peripherals and subsystems that the ATF
needs). As a Secure Monitor, the TF-A provides power management services
to other software components, via a standard API/ABI called PSCI. For
details of ATF, please refer to the sections

	"11 ARM Trusted Firmware"
and
	"22 Power Management"

in "S32G2_Linux_BSP36.0_User_Manual.pdf".

NOTICE:
    For hardware reasons, the power management features are only supported
    on S32G274A RDB REV B2 or newer boards.


6.5.1 STR verify steps
----------------------

STR(Sleep To Ram) is a complex power management feature and is a high-level
concept, implemented by the linux kernel and the ATF, and underlaid by the
S32G SoC’s Standby state. With ATF enabled, users can verify STR using the
following command after the board boot up:

	rtcwake -d rtc0 -m mem -s 10

this command will excute STR and try to wakeup the system with RTC after
10 seconds. If succeed, the output messages should like the following:

	root@nxp-s32g:~# rtcwake -d rtc0 -m mem -s 5
	rtcwake: assuming RTC uses UTC ...
	rtcwake: wakeup from "mem" using rtc0 at Thu Jan  1 00:27:29 1970
	PM: suspend entry (deep)
	Filesystems sync: 0.000 seconds
	Freezing user space processes ... (elapsed 0.001 seconds) done.
	OOM killer disabled.
	Freezing remaining freezable tasks ... (elapsed 0.001 seconds) done.
	printk: Suspending console(s) (use no_console_suspend to debug)
	NOTICE:  S32G TF-A: s32g_pwr_domain_off
	NOTICE:  S32G TF-A: s32g_pwr_domain_off_down_wfi: cpu = 1
	NOTICE:  S32G TF-A: s32g_pwr_domain_pwr_down_wfi: cpu = 2
	TICE:  S32G TF-A: s32g_pwr_domain_off
	NOTICE:  S32G TF-A: s32g_pwr_domain_pwr_down_wfi: OTICE:  S32G TF-A: s32g_get_sys_suspend_power_state
	NOTICE:  S32G TF-A: s32g_pwr_domain_suspend_pwrdown_early
	NOTICE:  S32G TF-A: s32g_pwr_domain_suspend
	NOTICE:  S32G TF-A: s32g_pwr_domain_pwr_down_wfi: cpu = 0
	NOTICE:  S32G TF-A: s32g_pwr_domain_suspend_finish
	NOTICE:  S32G TF-A: s32g_pwr_domain_on: booting up core 1
	NOTICE:  S32G TF-A: s32g_pwr_domain_on_finish: cpu 1 running
	NOTICE:  S32G TF-A: s32g_pwr_domain_on: booting up core 2
	NOTICE:  S32G TF-A: s32g_pwr_domain_on_finish: cpu 2 running
	NOTICE:  S32G TF-A: s32g_pwr_domain_on: booting up core 3
	NOTICE:  S32G TF-A: s32g_pwr_domain_on_finish: cpu 3 running
	s32cc-dwmac 4033c000.ethernet eth0: Link is Down
	s32cc-dwmac 4033c000.ethernet: Set TX clock to 125M
	s32cc-dwmac 4033c000.ethernet eth0: Link is Up - 1Gbps/Full - flow control rx/tx
	s32cc-dwmac 4033c000.ethernet eth0: Link is Down
	fsl-edma 40144000.dma-controller: WARN: There is non-idle channel.
	Disabling non-boot CPUs ...
	IRQ78: set affinity failed(-22).
	CPU1: shutdown
	psci: CPU1 killed (polled 4 ms)
	IRQ78: set affinity failed(-22).
	CPU2: shutdown
	psci: CPU2 killed (polled 4 ms)
	IRQ78: set affinity failed(-22).
	CPU3: shutdown
	psci: CPU3 killed (polled 4 ms)
	Enabling non-boot CPUs ...
	Detected VIPT I-cache on CPU1
	GICv3: CPU1: found redistributor 1 region 0:0x00000000508a0000
	CPU1: Booted secondary processor 0x0000000001 [0x410fd034]
	CPU1 is up
	Detected VIPT I-cache on CPU2
	GICv3: CPU2: found redistributor 100 region 0:0x00000000508c0000
	CPU2: Booted secondary processor 0x0000000100 [0x410fd034]
	CPU2 is up
	Detected VIPT I-cache on CPU3
	GICv3: CPU3: found redistributor 101 region 0:0x00000000508e0000
	CPU3: Booted secondary processor 0x0000000101 [0x410fd034]
	CPU3 is up
	s32cc-dwmac 4033c000.ethernet: phy mode set to RGMII
	s32cc-dwmac 4033c000.ethernet: Failed to reset the dma
	s32cc-dwmac 4033c000.ethernet eth0: stmmac_hw_setup: DMA engine initialization failed
	s32cc-dwmac 4033c000.ethernet eth0: configuring for phy/rgmii link mode
	OOM killer enabled.
	Restarting tasks ... done.
	PM: suspend exit
	root@nxp-s32g:~#

6.5.2 CPU Hotplug verify steps
------------------------------

With ATF enabled, CPU Hotplug is supported, below is the steps
to verify this feature:

  1. check current online cpu numbers

	root@nxp-s32g:~#  nproc
	4

  2. offline cpu1

	root@nxp-s32g:~# echo 0 > /sys/devices/system/cpu/cpu1/online
	NOTICE:  SIRQ78: set affinity failed(-22).
	process 201 (rngd) no longer affine to cpu1
	process 199 (rngd) no longer affine to cpu1
	CPU1: shutdown
	psci: CPU1 killed (polled 0 ms)
	root@nxp-s32g:~# nproc
	3

  3. online cpu1

	root@nxp-s32g:~# echo 1 > /sys/devices/system/cpu/cpu1/online
	NOTICE:  S32G TF-A: s32g_pwr_domain_on: booting up core 1
	NOTICE:  S32G TF-A: s32g_pwr_domain_on_finish: cpu 1 running
	Detected VIPT I-cache on CPU1
	GICv3: CPU1: found redistributor 1 region 0:0x00000000508a0000
	CPU1: Booted secondary processor 0x0000000001 [0x410fd034]
	root@nxp-s32g:~#
	root@nxp-s32g:~# nproc
	4
	root@nxp-s32g:~#

6.5.3 Known issues
------------------

For ATF feature, there are some known issues.

  1. USB devices can not be identified after STR

     Same as SDK, the usb devices can not be identified after STR, because
     the USB driver does not support STR currentlly, there is a STR supported
     driver list in section:
	"23.3 Suspend to RAM" in "S32G2_Linux_BSP36.0_User_Manual.pdf"

     And this list will be updated in future.


6.5.4 Build ATF
---------------

By default, the atf image is compiled and installed. If you want atf to be manually
compiled separately, use the following command：

        # bitbake atf-s32g

6.6 IPCF
--------

IPCF is short for "Inter-Platform Communication Framework" on NXP S32G
platform, it is designed to work on various hardware platforms and operating
systems. Prior to being used it needs to be integrated in the operating
systems running on each platform. For S32G, to use this feature, users need
to manually prepare application for M7 cores(refer to the following section
6.6.1 "IPCF application on M7 side"), and the A53 linux side components
have already integrated into wrlinux(please refer to the following section
6.6.2 "Enable IPCF feature in wrlinux").

6.6.1 IPCF application on M7 side
---------------------------------

Please note that, application on M7 side is not a pre-built binary file, it
should be built manually, as preparation, the following(all of them can be
found on Flexera) shoul be setup in the following order on user's local host
machine:

	1. S32 Design Studio 3.4
	2. S32 Design Studio 3.4 Development Packages for Offline Use,
	   Support for S32G Family
	3. Real Time Drivers (RTD) 4.4 version 3.0.0 D2112 (use file
	   with _updatesite.zip in the name and install through
	   Extensions and Updates in S32 Design Studio)
	4. IPCF version 4.5.0 D2201 (use file with _updatesite.zip in
	   the name and install through Extensions and Updates in
	   S32 Design Studio)

For detail informations about the above packages setup, installation and
build steps, please refer to the documents:

	"S32DS_Installation_Guide_3.4.0.pdf"
	"SW32_RTD_4.4_3.0.0_D2112_ReleaseNotes.pdf"
	"SW32G_IPCF_4.5.0_D2201_ReleaseNotes.pdf"

and etc., which can be found in related packages downloaded from flexra.

And if the IPCF application on M7 side build successfully following the
related documents, then users can find the binary files:

	"IPCF_Example_S32G274.bin" and "IPCF_Example_S32G399_M7_0.bin"

from S32DS IPCF example project.

6.6.2 Enable IPCF feature in wrlinux
------------------------------------

If users want to enable IPCF feature on A53 side linux system, please add
the following lines in the <project-build-dir>/conf/local.conf:

	IPCF_M7_APP_BIN_DIR = "/path/to/your-ipcf-m7-app/"
	IMAGE_INSTALL:append = ' ipc-shm'

then build the project as normal:

	bitbake wrlinux-image-std

the IPCF related drivers and M7 side app binaries(IPCF_Example_S32G274.bin and
IPCF_Example_S32G399_M7_0.bin) will be built into WIC image.

NOTICE:
    The M7 side binary default names are IPCF_Example_S32G274.bin and
IPCF_Example_S32G399_M7_0.bin, and they are defined by two variables
IPCF_M7_APP_BIN_NAME and IPCF_M7_APP_BIN_NAME_S32G3 respectively, users can
use different binary names by modifying these variables, or set related
variable(s) to empty if it is unneeded for users.


6.6.3 IPCF verify steps
-----------------------

If both the IPCF application on M7 side and IPCF related drivers in linux
are all build successfully, then users can follow the below steps to verify
this feature:

	1. dd WIC image(build following 6.6.2 section) into one SD-card

	2. using the SD-card to bootup the board

	3. stop in u-boot stage, and excute following commands

		a> disable Data Cache from uboot:
			=>dcache off
		b> zero-set SRAM shared memory used by both sample apps:
			=>mw.q 0x34000000 0x0 0x100000
		c> load IPCF binary in SRAM:
		   for S32G2:
			=>fatload mmc 0:1 0x80000000 IPCF_Example_S32G274_M7_0.bin
		   for S32G3:
			=>fatload mmc 0:1 0x80000000 IPCF_Example_S32G399_M7_0.bin
		   then:
			=>cp.q 0x80000000 0x34300000 0x30000
			=>dcache on;
		d> start M7 core (the argument is the address of the Interrupt Vector):
		   for S32G2:
			=>startm7 0x34401000;
		   for S32G3:
			=>startm7 0x34381000;
		e> boot Linux:
			=>boot

	4. after linux system startup, enable ipcf driver support on linux

		modprobe ipc-shm-sample


	5. run ipcf test command

		echo 10 > /sys/kernel/ipc-shm-sample/ping

If all the above steps succeed, the result messages should be like:

	root@nxp-s32g:~# echo 10 > /sys/kernel/ipc-shm-sample/ping
	ipc-shm-sample: starting demo...
	ipc-shm-sample: ch 0 >> 20 bytes: SENDING MESSAGES: 10
	ipc-shm-sample: ch 1 >> 32 bytes: #0 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 1 << 32 bytes: #0 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 2 >> 32 bytes: #1 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 2 << 32 bytes: #1 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 1 >> 32 bytes: #2 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 1 << 32 bytes: #2 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 2 >> 32 bytes: #3 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 2 << 32 bytes: #3 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 1 >> 32 bytes: #4 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 1 << 32 bytes: #4 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 2 >> 32 bytes: #5 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 2 << 32 bytes: #5 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 1 >> 32 bytes: #6 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 1 << 32 bytes: #6 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 2 >> 32 bytes: #7 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 2 << 32 bytes: #7 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 1 >> 32 bytes: #8 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 1 << 32 bytes: #8 HELLO WORLD! from CORE 4
	ipc-shm-sample: ch 2 >> 32 bytes: #9 HELLO WORLD! from KERNEL
	ipc-shm-sample: ch 0 << 20 bytes: REPLIED MESSAGES: 10
	ipc-shm-sample: ch 2 << 32 bytes: #9 HELLO WORLD! from CORE 4
	ipc-shm-sample: exit demo
	root@nxp-s32g:~#


6.7 Build U-Boot
----------------

By default, the u-boot image is compiled and installed. If you want u-boot to be manually
compiled separately, use the following command：

        # bitbake u-boot-s32

6.8 Templates
-------------

6.8.1 Omit_atf
--------------

This template is to skip the operation that installing fip.s32 to wic image.
To build a wic image without fip.s32, enable omit_atf template in your local.conf file:

	WRTEMPLATE = "feature/omit_atf"

6.8.2 m7_boot
-------------

This template is used to boot up NXP s32g platforms with cortex-M7 core.

6.8.2.1 m7 non-secure boot mode
-------------------------------

With this kind of boot up mode, Cortex-M7 core is brought up with m7-sample code firstly when powering on
NXP s32g platforms. And then the m7-sample code brings up Cortex-A53 core with atf code. This is called serial
boot up mode.
If users want to enable m7 boot mode, please add below contents in local.conf file when building WRLinux project.

	BB_NO_NETWORK = '0'
	WRTEMPLATE:append = " feature/m7_boot"
	CUSTOMER_RECIPES:wr-nxp-s32g += 'cortex-m-toolchain'
	CUSTOMER_RECIPES:wr-nxp-s32g += 'm7-sample'

6.8.2.2 m7 secure boot mode
---------------------------

m7 boot feature can be used to work with secure boot feature, it is called as m7 secure boot mode. With this mode,
HSE firmware verifies the m7-sample and atf images firstly, and then brings up the Cortex-M7 core with m7-sample image,
and then the m7-sample image brings up the Cortex-A53 core with atf image.
If users want to enable m7 secure boot mode, please add below contents in local.conf file when building WRLinux project.

	HSE_LOCAL_FIRMWARE_DIR = "<HSE firmware path>"
	HSE_FW_NAME_S32G2 = "<S32G2 HSE firmware name>"
	HSE_FW_NAME_S32G3 = "<S32G2 HSE firmware name>"
	BB_NO_NETWORK = '0'
	WRTEMPLATE:append = " feature/m7_boot"
	CUSTOMER_RECIPES:wr-nxp-s32g += 'cortex-m-toolchain'
	CUSTOMER_RECIPES:wr-nxp-s32g += 'm7-sample'

Note:
About the secure boot information, please refer to the README in s32g-secure-boot layer.

6.8.3 secure-boot-parallel
--------------------------

This template is used to bring up Cortex-M7 and Cortex-A53 parallel under secure boot mode.
With this boot up mode, HSE firmware verifies the m7-sample and atf images firstly, and then brings up the Cortex-M7 and
Cortex-A53 cores parallel.
If users want to enable parallel secure boot mode, please add below contents in local.conf file when building WRLinux project.

	HSE_LOCAL_FIRMWARE_DIR = "<HSE firmware path>"
	HSE_FW_NAME_S32G2 = "<S32G2 HSE firmware name>"
	HSE_FW_NAME_S32G3 = "<S32G2 HSE firmware name>"
	BB_NO_NETWORK = '0'
	WRTEMPLATE:append = " feature/secure-boot-parallel"
	CUSTOMER_RECIPES:wr-nxp-s32g += 'cortex-m-toolchain'
	CUSTOMER_RECIPES:wr-nxp-s32g += 'm7-sample'

Note:
The parallel boot mode only can be supported under secure boot mode.

6.9 dm-verity
-------------
In order to use the dm-verity feature, you should enable the dm-verity template first.
Please add the following to your setup line:
	--templates feature/dm-verity

As the rootfs is read only when dm-verity is enabled, the pkg_postinst_ontarget mechanism
can't be used. We must decide which specific SoC this rootfs will be used for and set the
corresponding value to S32G_SOC_VARIANT in your conf/local.conf. So far, the supported
values are "s32g2" and "s32g3".
	S32G_SOC_VARIANT ?= "s32g2" or "s32g3"