BOOTLOADER

The Bootloader module provides APIs to write bootloader applications for various boot media like OSPI, UART, SOC memory etc.

Note

The bootloader driver is tested only in the context of a single thread and should be used only sequentially to boot cores to prevent potential errors and ensure stability. Also the current design of bootloader does not support parallel boot even when run in multiple threads.

Bootloader Migration Guidelines 

While migrating to 11.00.00 FreeRTOS SDK, using the older example.syscfg file for bootloader examples with ospi dma enabled, can throw following error in gui, while running the command make syscfg-gui Bootloader adds multiple udma instances

While using make command to build the example, it will throw following error

error: CONFIG_BOOTLOADER_FLASH_LINUX(/drivers/bootloader/bootloader) udmaDriver.$name: Duplicate name: 'CONFIG_UDMA0' also exists on instance(s) of UDMA
error: CONFIG_FLASH0(/board/flash/flash) serialFlashDriver.peripheralDriver.udmaDriver.$name: Duplicate name: 'CONFIG_UDMA0' also exists on instance(s) of UDMA
error: CONFIG_BOOTLOADER_FLASH_LINUX(/drivers/bootloader/bootloader) udmaBlkCopyChannel.$name: Duplicate name: 'CONFIG_UDMA_BLKCOPY_CH0' also exists on instance(s) of UDMA Block Copy Channel Configuration
error: CONFIG_FLASH0(/board/flash/flash) serialFlashDriver.peripheralDriver.udmaBlkCopyChannel.$name: Duplicate name: 'CONFIG_UDMA_BLKCOPY_CH0' also exists on instance(s) of UDMA Block Copy Channel Configuration
error: CONFIG_BOOTLOADER_FLASH_LINUX(/drivers/bootloader/bootloader) udmaDriver.instance: Same instance cannot be selected
error: CONFIG_FLASH0(/board/flash/flash) serialFlashDriver.peripheralDriver.udmaDriver.instance: Same instance cannot be selected

To fix this, update the example.syscfg, for every instance of bootloader define udma driver and udma block copy channel, refer the below lines to update example.syscfg

const udma                                           = scripting.addModule("/drivers/udma/udma", {}, false);
const udma1                                          = udma.addInstance({}, false);
udma1.$name                                          = "CONFIG_UDMA0";
flash1.serialFlashDriver.peripheralDriver.udmaDriver = udma1;
bootloader1.udmaDriver                               = udma1;
bootloader2.udmaDriver                               = udma1;
bootloader3.udmaDriver                               = udma1;

const udma_blkcopy_channel                                   = scripting.addModule("/drivers/udma/udma_blkcopy_channel", {}, false);
const udma_blkcopy_channel1                                  = udma_blkcopy_channel.addInstance({}, false);
udma_blkcopy_channel1.$name                                  = "CONFIG_UDMA_BLKCOPY_CH0";
flash1.serialFlashDriver.peripheralDriver.udmaBlkCopyChannel = udma_blkcopy_channel1;
bootloader1.udmaBlkCopyChannel                               = udma_blkcopy_channel1;
bootloader2.udmaBlkCopyChannel                               = udma_blkcopy_channel1;
bootloader3.udmaBlkCopyChannel                               = udma_blkcopy_channel1;

Migration Guide 11.02 to 11.03 - AM62Ax 

Note

This section highlights linker changes from SDK 11.02 to 11.03 for AM62Ax.

Migration Guide 11.02 to 12.00 

Note

This section highlights linker changes from SDK 11.02 to 12.00.

`gAtcmBaseAddr` symbol required in SBL linker.cmd 

SBL startup code (entered via -e_vectors_sbl) now references gAtcmBaseAddr to configure the ATCM base address at boot time.
Custom SBL linker.cmd files that specify -e_vectors_sbl as the entry point must define this symbol, or the linker will report an undefined symbol error.

Old linker.cmd:

--heap_size=0x8000
-e_vectors_sbl

New linker.cmd:

--heap_size=0x2000

/* ATCM base address - required when using -e_vectors_sbl entry point */
gAtcmBaseAddr = 0x78000000;

-e_vectors_sbl

Note

If ATCM is also needed for SBL heap and interrupt stacks, add the ATCM region to MEMORY and relocate .sysmem and stack sections to ATCM. An MPU entry for ATCM is needed to be added to example.syscfg as well if so used.

MEMORY { 
   ATCM     (RWIX) : ORIGIN = 0x78000000 LENGTH = 0x8000 
   HSM_RAM  (RWIX) : ORIGIN = 0x43C00000 LENGTH = 0x3E000 
}

SECTIONS
{
    .sysmem: {} palign(8) > ATCM
    GROUP {
        .irqstack:  {. = . + __IRQ_STACK_SIZE;}  align(8)
        .fiqstack:  {. = . + __FIQ_STACK_SIZE;}  align(8)
    } > ATCM
    GROUP {
        .svcstack:   {. = . + __SVC_STACK_SIZE;}   align(8)
        .abortstack: {. = . + __ABORT_STACK_SIZE;}  align(8)
    } > ATCM
}

const mpu_armv7_ATCM  = mpu_armv7.addInstance();
mpu_armv7_ATCM.$name    = "ATCM_SOC";
mpu_armv7_ATCM.baseAddr = 0x78000000;
mpu_armv7_ATCM.size     = 15;

Features Supported 

OSPI Boot
MEM Boot (Boot media is SOC memory)
API to parse multicore appimage
Separate APIs to boot self and non-self cores

SysConfig Features 

Note

It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

Bootloader instance name
Boot Media to be used
Boot Image offset

R5 Dual Core Support 

RBL boots the R5 in eFUSE default, which is split mode. SBL (Secondary Boot Loader) follows the same and keeps the R5s in split mode. As of now the lock step configuration of dual R5 is not supported from bootloader.

Example Usage 

Include the below file to access the APIs

#include <stdio.h>
#include <drivers/bootloader.h>

Instance Open Example 

    gBootloaderHandle = Bootloader_open(0, NULL);
    DebugP_assert(gBootloaderHandle != NULL);

Booting Cores Example 

    int32_t status = SystemP_SUCCESS;

	status = Bootloader_parseMultiCoreAppImage(gBootloaderHandle, &gBootImageInfo);

	if(SystemP_SUCCESS == status && gBootloaderHandle != NULL)
    {
        if(status == SystemP_SUCCESS)
        {
            gBootImageInfo.cpuInfo[CSL_CORE_ID_M4FSS0_0].clkHz = Bootloader_socCpuGetClkDefault(CSL_CORE_ID_M4FSS0_0);
            status = Bootloader_bootCpu(gBootloaderHandle, &gBootImageInfo.cpuInfo[CSL_CORE_ID_M4FSS0_0]);
        }
        if(status == SystemP_SUCCESS)
        {
            gBootImageInfo.cpuInfo[CSL_CORE_ID_M4FSS0_0].clkHz = Bootloader_socCpuGetClkDefault(CSL_CORE_ID_R5FSS1_0);
            status = Bootloader_bootCpu(gBootloaderHandle, &gBootImageInfo.cpuInfo[CSL_CORE_ID_R5FSS1_0]);
        }
        if(status == SystemP_SUCCESS)
        {
            gBootImageInfo.cpuInfo[CSL_CORE_ID_R5FSS1_1].clkHz = Bootloader_socCpuGetClkDefault(CSL_CORE_ID_R5FSS1_1);
            status = Bootloader_bootCpu(gBootloaderHandle, &gBootImageInfo.cpuInfo[CSL_CORE_ID_R5FSS1_1]);
        }
        if(status == SystemP_SUCCESS)
        {
            gBootImageInfo.cpuInfo[CSL_CORE_ID_R5FSS0_0].clkHz = Bootloader_socCpuGetClkDefault(CSL_CORE_ID_R5FSS0_0);
            gBootImageInfo.cpuInfo[CSL_CORE_ID_R5FSS0_1].clkHz = Bootloader_socCpuGetClkDefault(CSL_CORE_ID_R5FSS0_1);
            /* Reset self cluster, both Core0 and Core 1. Init RAMs and run the app  */
            status = Bootloader_bootSelfCpu(gBootloaderHandle, &gBootImageInfo);
        }
    }

Instance Close Example 

    Bootloader_close(gBootloaderHandle);

API Reference 

Defines

FREERTOS_SMP_RPRC_CORE_ID

FREERTOS_SMP_NO_OF_CORES

FREERTOS_SMP_BOOT_CORE

FREERTOS_SMP_CSL_CORE_ID_MAX

BOOTLOADER_DMA_CHANNEL_TYPE

Typedefs

typedef void __attribute__((__noreturn__)) (*Bootloader_SelfCoreJump)(void)

Function pointer to jump a self core to specific code location in AM62x SOC.

This function pointer is used to assign the jump address for self core after all the other cores are initialised. Since the self core is already up, we jump the self core to load adresss as present in the appimage.

Functions

int32_t Bootloader_socCpuRequest(uint32_t cpuId)

Request for a particular CPU in the AM62x SOC.

This API internally makes Sciclient calls to request control of the CPU

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: SystemP_SUCCESS on success, else failure

int32_t Bootloader_socCpuRelease(uint32_t cpuId)

Release a particular CPU in the AM62x SOC.

This API internally makes Sciclient calls to release control of the CPU

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: SystemP_SUCCESS on success, else failure

int32_t Bootloader_socCpuSetClock(uint32_t cpuId, uint32_t cpuHz)

Set the clock of a particular CPU in the AM62x SOC.

This API internally makes Sciclient calls to set CPU clock

Parameters:

cpuId – [in] The CSL ID of the core
cpuHz – [in] Desired clock frequency of the CPU in Hertz

Returns:

SystemP_SUCCESS on success, else failure

uint64_t Bootloader_socCpuGetClock(uint32_t cpuId)

Get the clock of a particular CPU in the AM62x SOC.

This API internally makes Sciclient calls to get the current clock frequency of CPU

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: Current clock speed of the CPU

uint32_t Bootloader_socCpuGetClkDefault(uint32_t cpuId)

Get the default clock of a particular CPU in the AM62x SOC.

This API queries and internal lookup table to fetch the default clock speed at which a particular CPU should run.

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: Default clock speed of the CPU

int32_t Bootloader_socCpuPowerOnReset(uint32_t cpuId, void *socCoreOpMode)

Do power-on-reset of a particular CPU in the AM62x SOC.

This API is called only when booting a non-self CPU.

Parameters:

cpuId – [in] The CSL ID of the core
socCoreOpMode – Lockstep/Dual core mode as per setting in syscfg.

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_socCpuResetRelease(uint32_t cpuId, uintptr_t entryPoint)

Release a particular CPU in the AM62x SOC from reset.

This API is called only when booting a non-self CPU. There is a different API Bootloader_socCpuResetReleaseSelf in the case of a self CPU

Parameters:

cpuId – [in] The CSL ID of the core
entryPoint – [in] The entryPoint of the CPU, from where it should start execution

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_socCpuResetReleaseSelf(): Release self CPU in the AM62x SOC from reset.

void __attribute__((__noreturn__)) Bootloader_socSelfCPUjump(): Jump the self cpu to specified load address.

int32_t Bootloader_socCpuSetEntryPoint(uint32_t cpuId, uintptr_t entryPoint)

Set entry point for self CPU in the AM62x SOC from reset.

This API need not be called when booting a non-self CPU. The entry point can be specified in the Bootloader_socCpuResetRelease function itself

Parameters:

cpuId – [in] The CSL ID of the core
entryPoint – [in] The entryPoint of the CPU, from where it should start execution

Returns:

SystemP_SUCCESS on success, else failure

uint32_t Bootloader_socTranslateSectionAddr(uint32_t cslCoreId, uint32_t addr)

Translate a CPU address to the SOC address wherever applicable.

This API need not be called when booting a non-self CPU. The entry point can be specified in the Bootloader_socCpuResetRelease function itself

Parameters:

cslCoreId – [in] The CSL ID of the core
addr – [in] The CPU addr

Returns:

SystemP_SUCCESS on success, else failure

uint32_t Bootloader_socRprcToCslCoreId(uint32_t rprcCoreId)

Obtain the CSL core ID of a CPU from its RPRC core ID.

Parameters:: rprcCoreId – [in] The RPRC ID of the core
Returns:: CSL core ID of a CPU

bool Bootloader_socIsSmpEnable(uint32_t rprcCoreId)

Check whether the smp is enabled or not for the soc.

Parameters:: rprcCoreId – [in] The RPRC ID of the core
Returns:: true if smp is enabled otherwise false

uint32_t *Bootloader_socGetSelfCpuList(void)

Get the list of self cpus in the SOC.

Returns:: List of self cpus ending with an invalid core id

char *Bootloader_socGetCoreName(uint32_t cpuId)

Get the name of a core.

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: Name of the CPU

int32_t Bootloader_socMemInitCpu(uint32_t cpuId)

Initialize the core memories of a specific core.

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: SystemP_SUCCESS on success, else failure

uint32_t Bootloader_socGetSciclientCpuProcId(uint32_t cpuId)

Obtain the Sciclient Proc Id corresponding to the CSL core ID.

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: CSL core ID of a CPU

uint32_t Bootloader_socGetSciclientCpuDevId(uint32_t cpuId)

Obtain the Sciclient Device Id corresponding to the CSL core ID.

Parameters:: cpuId – [in] The CSL ID of the core
Returns:: CSL core ID of a CPU

int32_t Bootloader_socSecHandover(void)

API to trigger the security handover from SYSFW.

Returns:: SystemP_SUCCESS on success, else failure

int32_t Bootloader_socWaitForFWBoot(void)

API to wait for boot notification from SYSFW/ROM.

Returns:: SystemP_SUCCESS on success, else failure

int32_t Bootloader_socOpenFirewalls(void)

API to open required firewalls using SYSFW.

Returns:: SystemP_SUCCESS on success, else failure

int32_t Bootloader_socAuthImage(uint32_t certLoadAddr)

API to authenticate (and decrypt if needed) an appimage using SYSFW.

Parameters:: certLoadAddr – [in] The SOC address pointing to the certificate+appimage
Returns:: SystemP_SUCCESS on success, else failure

uint32_t Bootloader_socIsAuthRequired(void)

API to check if authentication is required for the device. Checks the SYS_STATUS register to see if device is GP, HS-FS, HS-SE etc.

Returns:: TRUE (1U) if authentication required, FALSE (0U) if not.

uint32_t Bootloader_socIsMCUResetIsoEnabled()

Check if MCU R5 is reset isolated.

Returns:: TRUE (1U) if MCU R5 is reset isolated, else return 0.

void Bootloader_socCpuPowerOff(uint32_t cpuId)

Power off a core.

Parameters:: cpuId – [in] The CSL ID of the core

int32_t Bootloader_socClrIOIsolationOnLPMExit(void)

Clear IO isolation if LPM exit is detected. As the wake pad number gets cleared after removing isolation, it is saved in MMR for later use.

Returns:: SystemP_SUCCESS on success, else failure

struct Bootloader_CoreBootInfo

#include <bootloader_soc.h>

Data structure containing information about a core specific to the AM62x SOC.

This structure is used to store the data about cores in the SoC in the form of a lookup table which will be used by various APIs.

Public Members

uint32_t tisciProcId

uint32_t tisciDevId

uint32_t tisciClockId

uint32_t defaultClockHz

char coreName[8]

Bootloader Driver API/interface file.

Bootloader driver implementation callbacks

typedef int32_t (*Bootloader_imgOpenFxn)(void *args, Bootloader_Params *params)

Driver implementation to open a specific bootloader driver - Memory, OSPI, UART, MMCSD etc.

Typically this callback is hidden from the end application and is implemented when a new boot media needs to be supported.

Param args:: [in] Boot media specific arguments, obtained from the config
Param params:: [in] User controllable params
Return:: SystemP_SUCCESS on success, else failure

typedef int32_t (*Bootloader_imgReadFxn)(void *dstAddr, uint32_t length, void *args)

Driver implementation to read from boot media using a specific bootloader driver - Memory, OSPI, UART, MMCSD etc.

Typically this callback is hidden from the end application and is implemented when a new boot media needs to be supported.

Param dstAddr:: [in] Destination address to which the data is to be read into
Param length:: [in] Length in bytes of the data to be read
Param args:: [in] Boot media specific arguments, obtained from the config
Return:: SystemP_SUCCESS on success, else failure

typedef uint32_t (*Bootloader_imgOffsetFxn)(void *args)

Driver implementation to get the current offset in the boot media.

Typically this callback is hidden from the end application and is implemented when a new boot media needs to be supported.

Param args:: [in] Boot media specific arguments, obtained from the config
Return:: Current Offset

typedef void (*Bootloader_imgSeekFxn)(uint32_t location, void *args)

Driver implementation to move read offset on boot media using a specific bootloader driver - Memory, OSPI, UART, MMCSD etc.

Typically this callback is hidden from the end application and is implemented when a new boot media needs to be supported.

Param dstAddr:: [in] Destination address to which the data is to be read into
Param length:: [in] Length in bytes of the data to be read
Param args:: [in] Boot media specific arguments, obtained from the config
Return:: SystemP_SUCCESS on success, else failure

typedef void (*Bootloader_imgCloseFxn)(void *handle, void *args)

Driver implementation to close a specific bootloader driver - Memory, OSPI, UART, MMCSD etc.

Typically this callback is hidden from the end application and is implemented when a new boot media needs to be supported.

Param handle:: [in] Handle returned from Bootloader_imgOpen
Param args:: [in] Boot media specific arguments, obtained from the config
Return:: SystemP_SUCCESS on success, else failure

typedef int32_t (*Bootloader_imgCustomFxn)(void *args)

Driver implementation to enable a custom function for a specific bootloader driver - Memory, OSPI, UART, MMCSD etc.

Typically this callback is hidden from the end application and is implemented when a new boot media needs to be supported.

Param args:: [in] Boot media specific arguments, obtained from the config
Return:: SystemP_SUCCESS on success, else failure

Defines

BOOTLOADER_INVALID_ID: Invalid ID magic number to be used for initializations.

BOOTLOADER_OPMODE_LOCKSTEP: Operating mode type.

BOOTLOADER_OPMODE_STANDALONE

BOOTLOADER_MEDIA_MEM: Boot media IDs.

BOOTLOADER_MEDIA_FLASH

BOOTLOADER_MEDIA_EMMC

BOOTLOADER_MEDIA_SD

BOOTLOADER_MEDIA_BUFIO

BOOTLOADER_MEDIA_UART

Typedefs

typedef void *Bootloader_Handle: Handle to the Bootloader driver returned by Bootloader_open()

Enums

enum Bootloader_AppImageLoadStatus

AppImage load status.

Values:

enumerator BOOTLOADER_IMAGE_NOT_LOADED

enumerator BOOTLOADER_IMAGE_LOADED

Functions

void Bootloader_Params_init(Bootloader_Params *params)

Initialize Bootloader params.

Parameters:: params – [out] Pointer to a Bootloader_Params structure

void Bootloader_BootImageInfo_init(Bootloader_BootImageInfo *bootImageInfo)

Initialize BootImage info.

Parameters:: bootImageInfo – [out] Pointer to a Bootloader_BootImageInfo structure

void Bootloader_CpuInfo_init(Bootloader_CpuInfo *cpuInfo)

Initialize CPU info.

Parameters:: cpuInfo – [out] Pointer to a Bootloader_CpuInfo structure

Bootloader_Handle Bootloader_open(uint32_t instanceNum, Bootloader_Params *openParams)

Open bootloader driver.

Make sure the SOC periheral driver is open’ed before calling this API. Drivers_open function generated by SysCfg opens the underlying SOC peripheral driver, e.g OSPI.

Global variables Bootloader_Config gBootloaderConfig[] and uint32_t gBootloaderConfigNum is instantiated by SysCfg to describe the boot media and other configuration based on user selection in SysCfg.

Parameters:

instanceNum – [in] Index within Bootloader_Config gBootloaderConfig[] denoting the bootloader driver to open
openParams – [in] Open parameters

Returns:

Handle to bootloader driver which should be used in subsequent API call

Returns:

NULL in case of failure

void Bootloader_close(Bootloader_Handle handle)

Close bootloader driver.

Parameters:: handle – [in] Bootloader driver handle from Bootloader_open

int32_t Bootloader_loadCpu(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

API to load a non-self CPU.

This API will load RPRC images a non-self CPU, i.e a CPU on which the bootloader application is not running. This API is not applicable for cores from self cluster. They will be loaded by the Bootloader_loadSelfCpu API.

NOTE: No checks are done to confirm non-self CPU ID is passed, user need to make sure non-self CPU ID is passed, else the load could fail.

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
cpuInfo – [in] Data structure containing information regarding the CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_loadSelfCpu(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

API to load self CPU.

This API will load RPRC images on self CPU, i.e a CPU on which the bootloader application is running

NOTE: No checks are done to confirm self CPU ID is passed, user need to make sure self CPU ID is passed, else the load could fail.

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
cpuInfo – [in] Data structure containing information regarding the CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_runCpu(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

API to run a non-self CPU.

This API will run a non-self CPU, i.e a CPU on which the bootloader application is not running. This API is not applicable for cores from self cluster. They will be run by the Bootloader_runSelfCpu API. It is expected that this API be called after Bootloader_loadCpu API

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
cpuInfo – [in] Data structure containing information regarding the CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_runSelfCpu(Bootloader_Handle handle, Bootloader_BootImageInfo *bootImageInfo)

API to boot self CPU.

This API will boot self CPU, i.e a CPU on which the bootloader application is running. It is expected that this API be called after Bootloader_loadSelfCpu API

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
bootImageInfo – [in] Data structure of type Bootloader_BootImageInfo containing information regarding self CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

Returns:

SystemP_SUCCESS on success, else failure

void Bootloader_JumpSelfCpu(void)

API to jump self CPU.

This API will make self CPU jump to another code location, i.e a CPU on which the bootloader application is running. It is expected that this API be called after Bootloader_loadSelfCpu API

int32_t Bootloader_bootCpu(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

API to boot a non-self CPU.

This API will boot a non-self CPU, i.e a CPU on which the bootloader application is not running. Now if the self CPU is a dual core CPU, like a Cortex R5, this API is not applicable for the second core of the self CPU. That will be booted by the Bootloader_bootSelfCpu API.

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
cpuInfo – [in] Data structure containing information regarding the CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_bootSelfCpu(Bootloader_Handle handle, Bootloader_BootImageInfo *bootImageInfo)

API to boot self CPU.

This API will boot self CPU, i.e a CPU on which the bootloader application is running

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
bootImageInfo – [in] Data structure of type Bootloader_BootImageInfo containing information regarding self CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_parseMultiCoreAppImage(Bootloader_Handle handle, Bootloader_BootImageInfo *bootImageInfo)

Parse Multicore Appimage.

When the booting is done through some boot media, unlike loading via CCS, the application binaries for each core applicable are converted into a file format ‘.rprc’ and combined together into a multicore appimage binary. The bootloader needs to read this appimage, and load the binaries correctly into memories. This API helps in parsing the multicore appimage and filling the metadata in the bootImageInfo structure passed.

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
bootImageInfo – [in] Data structure of type Bootloader_BootImageInfo which will be filled

Returns:

SystemP_SUCCESS on success, else failure

int32_t Bootloader_rprcImageParseEntryPoint(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

Parse entrypoint from RPRC.

This API reads the RPRC image to parse the entry points of a particular CPU

int32_t Bootloader_rprcImageLoad(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

Load application binaries into SOC memory.

This API loads the application binaries for each core applicable is loaded from the boot media to the SOC memory

int32_t Bootloader_runSelfCpuWithLinux()

API to boot self CPU with Linux.

This API will boot self CPU, i.e a CPU on which the bootloader application is running. It is expected that this API be called after Bootloader_loadSelfCpu API. This API does not perform a security handoff

Returns:: SystemP_SUCCESS on success, else failure

uint32_t Bootloader_getMulticoreImageSize(Bootloader_Handle handle)

API to fetch the size of the multicore image.

This API simply returns the internal global variable which gets updated everytime a section is loaded. So this API should only be called after all the rprc loading is complete.

Parameters:: handle – Bootloader driver handle from Bootloader_open
Returns:: Size of the multicore image size

uint32_t Bootloader_isCorePresent(Bootloader_Handle handle, uint32_t cslCoreId)

API to check if a particular core’s RPRC image is present in the multicore image.

This API checks the csl core id against an internally maintained bitmap which will be populated after parsing the image. So this API should be called only after the multicore image is parsed.

Parameters:

handle – Bootloader driver handle from Bootloader_open
cslCoreId – CSL core ID of the interested core

Returns:

TRUE if the given core’s rprc is present in the multicore image

uint32_t Bootloader_getBootMedia(Bootloader_Handle handle)

API to get the selected boot media in the bootloader instance.

This API returns the selected boot media. This data will be filled by sysconfig

Parameters:: handle – [in] Bootloader driver handle from Bootloader_open
Returns:: Boot media ID of the selected media

void Bootloader_ReservedMemInit(uint32_t startAddress, uint32_t regionlength)

API to set the memory region of bootloader.

This API is used to set the memory region of bootloader.

Parameters:

startAddress – [in] Start address of the memory region for bootloader.
regionlength – [in] Length of the memory region of bootloader.

void Bootloader_powerOffCpu(Bootloader_Handle handle, Bootloader_CpuInfo *cpuInfo)

API to power off a core.

Parameters:

handle – Bootloader driver handle from Bootloader_open
cpuInfo – [in] Data structure containing information regarding the CPU. This should have been filled by the Bootloader_parseMultiCoreAppImage API

int32_t Bootloader_parseAppImage(Bootloader_Handle handle, Bootloader_BootImageInfo *bootImageInfo)

API to Parse Multicore Appimage.

This API helps in parsing the multicore appimage and filling the metadata in the bootImageInfo structure passed. This API should be called only after authentication and decryption is done.

Parameters:

handle – [in] Bootloader driver handle from Bootloader_open
bootImageInfo – [in] Data structure of type Bootloader_BootImageInfo which will be filled

Returns:

SystemP_SUCCESS on success, else failure

void Bootloader_openDma(): API to open DMA channel.

void Bootloader_closeDma(): API to close DMA channel.

struct Bootloader_Params

#include <bootloader_rprc.h>

Parameters passed during Bootloader_open()

Public Members

uint32_t memArgsAppImageBaseAddr

uint8_t *bufIoTempBuf

uint32_t bufIoTempBufSize

uint32_t bufIoDeviceIndex

struct Bootloader_Fxns

#include <bootloader_rprc.h>

Driver implementation callbacks.

Public Members

Bootloader_imgOpenFxn imgOpenFxn

Bootloader_imgReadFxn imgReadFxn

Bootloader_imgOffsetFxn imgOffsetFxn

Bootloader_imgSeekFxn imgSeekFxn

Bootloader_imgCloseFxn imgCloseFxn

Bootloader_imgCustomFxn imgCustomFxn

struct Bootloader_Config

#include <bootloader_rprc.h>

Bootloader driver configuration, these are filled by SysCfg based on the boot media selected.

Public Members

Bootloader_Fxns *fxns

void *args

uint32_t bootMedia

uint32_t bootImageSize

uint32_t coresPresentMap

uint8_t *scratchMemPtr

void *socCoreOpMode

uint32_t enableDma

struct Bootloader_CpuInfo

#include <bootloader_rprc.h>

Data structure containing information related to a particular CPU, required for RPRC loading.

Public Members

uint32_t cpuId

uint32_t clkHz

uint32_t rprcOffset

uintptr_t entryPoint

bool smpEnable

struct Bootloader_BootImageInfo

#include <bootloader_rprc.h>

Data structure containing information related all CPUs, this will be filled by Bootloader_parseMultiCoreAppImage.

Public Members

Bootloader_CpuInfo cpuInfo[CSL_CORE_ID_MAX]

struct Bootloader_LoadImageParams

#include <bootloader_rprc.h>

Data structure containing necessary structs to load AppImage on different CPUs.

Public Members

Bootloader_BootImageInfo bootImageInfo

Bootloader_Params bootParams

Bootloader_Handle bootHandle

uint8_t coreId

Bootloader_AppImageLoadStatus loadStatus