SDL DPL

The SDL requires the application to provide an DPL implementation for various functionalities in order to keep SDL as OS-agnostic. Primarily, the SDL requires DPL implementations for interrupt registration and enable/disable, and also for a delay mechanism needed for POK programming.

Features Supported

The SDL DPL layer provides support for the application to define the following functionalities to be used by SDL:

Interrupt Enable/Disable
Interrupt Register/De-register
Address Translation
Delay

These features are provided by the application by calling SDL_DPL_init() with the appropriate function pointers.

SysConfig Features

None

Features NOT Supported

None

Important Usage Guidelines

SDL_DPL_init() must be called before using any SDL module that utilizes the SDL DPL APIs.

Example Usage

The SDL provides a sample implementation of these APIs as part of the SDL examples. The sample implementation re-uses PDK DPL APIs from the SDK in order to provide the services. This is verified with the following Operating Systems:

Non-OS (Baremetal)

The existing baremetal sample DPL interface can be used, or the application may implement it’s own. To use the existing sample interface:

Add the source file dpl_interface.c (located in example/dpl/src/) to the application’s build
Include the header dpl_interface.h (located in example/dpl/) to the application’s source file
Call the example’s DPL initializtion function SDL_TEST_dplInit() to initialize the DPL. Do this before calling any SDL APIs.

Alternatively, the application may implement it’s own DPL. An example of how to do this is shown below

Include the below file to access the APIs

#include <sdl/sdl_dpl.h>

Define the DPL APIs

        HwiP_Object gHwiObject;

        pSDL_DPL_HwipHandle SDL_TEST_registerInterrupt(SDL_DPL_HwipParams *pParams)
        {
            HwiP_Params hwipParams;
            HwiP_Params_init(&hwipParams);

            hwipParams.args = (void *)pParams->callbackArg;
            /*
             * For M4F, external interrupt #10 at NVIC is
             * 16 internal interrupts + external interrupt number at NVIC
             */
            hwipParams.intNum = pParams->intNum + 16;
            hwipParams.callback = pParams->callback;

            HwiP_construct(&gHwiObject, &hwipParams);

            return &gHwiObject;
        }

        int32_t SDL_TEST_deregisterInterrupt(pSDL_DPL_HwipHandle handle)
        {
            HwiP_destruct(handle);
            return SDL_PASS;
        }

        int32_t SDL_TEST_enableInterrupt(uint32_t intNum)
        {
            HwiP_enableInt(intNum);
            return SDL_PASS;
        }

        int32_t SDL_TEST_disableInterrupt(uint32_t intNum)
        {
            HwiP_disableInt(intNum);
            return SDL_PASS;
        }

        void* SDL_TEST_addrTranslate(uint64_t addr, uint32_t size)
        {
            uint32_t transAddr = (uint32_t)(-1);

            transAddr = (uint32_t)AddrTranslateP_getLocalAddr(addr);

            return (void *)transAddr;
        }

Initalize the DPL Interface

        SDL_DPL_Interface dpl_interface =
        {
            .enableInterrupt = (pSDL_DPL_InterruptFunction) SDL_TEST_enableInterrupt,
            .disableInterrupt = (pSDL_DPL_InterruptFunction) SDL_TEST_disableInterrupt,
            .registerInterrupt = (pSDL_DPL_RegisterFunction) SDL_TEST_registerInterrupt,
            .deregisterInterrupt = (pSDL_DPL_DeregisterFunction) SDL_TEST_deregisterInterrupt,
            .delay = (pSDL_DPL_DelayFunction) ClockP_sleep,
            .addrTranslate = (pSDL_DPL_AddrTranslateFunction) SDL_TEST_addrTranslate
        };

        int32_t main(void)
        {
            SDL_ErrType_t ret = SDL_PASS;

            ret = SDL_DPL_init(&dpl_interface);

            return ret;
        }

API Reference

This file contains the SDL DPL API’s.

Provides the APIs for DPL.

Typedefs

typedef void (*pSDL_DPL_InterruptCallbackFunction)(void *arg): Prototype for the interrupt callback function.

typedef void *pSDL_DPL_HwipHandle

typedef int32_t (*pSDL_DPL_InterruptFunction)(int32_t intNum): Prototype for the interrupt enable/disable functions.

typedef pSDL_DPL_HwipHandle (*pSDL_DPL_RegisterFunction)(SDL_DPL_HwipParams *pParams): Prototype for the interrupt registration function.

typedef int32_t (*pSDL_DPL_DeregisterFunction)(pSDL_DPL_HwipHandle handle): Prototype for the interrupt de-register function.

typedef int32_t (*pSDL_DPL_DelayFunction)(int32_t ndelay): Prototype for the delay function.

typedef void *(*pSDL_DPL_AddrTranslateFunction)(uint64_t addr, uint32_t size): Prototype for address translation function.

typedef int32_t (*pSDL_DPL_globalDisableInterruptsFunction)(uintptr_t *key): Prototype for the interrupt global disable function.

typedef int32_t (*pSDL_DPL_globalRestoreInterruptsFunction)(uintptr_t key): Prototype for the interrupt global restore function.

Functions

int32_t SDL_DPL_init(SDL_DPL_Interface *dplInterface)

DPL init.

This function initializes the DPL interface structure with the functions provided by the application. These functions are application dependent, so it is required to be passed by the user.

Parameters:: dplInterface – [IN] DPL interface structure.
Returns:: The SDL error code for the API. If dplInterface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

int32_t SDL_DPL_enableInterrupt(int32_t intNum)

DPL enable interrupt.

This function will enable the specific interrupt number passed.

Parameters:: intNum – [IN] Interrupt Number
Returns:: The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

int32_t SDL_DPL_disableInterrupt(int32_t intNum)

DPL disable interrupt.

This function will disable the specific interrupt number passed.

Parameters:: intNum – [IN] Interrupt Number
Returns:: The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

int32_t SDL_DPL_registerInterrupt(SDL_DPL_HwipParams *pParams, pSDL_DPL_HwipHandle *handle)

DPL register interrupt.

This function will register the specific interrupt number passed.

Parameters:

pParams – [IN] Parameters for interrupt registration
handle – [OUT] Handle for this registered interrupt

Returns:

The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

int32_t SDL_DPL_deregisterInterrupt(pSDL_DPL_HwipHandle handle)

DPL deregister interrupt.

This function will deregister the specific interrupt number passed.

Parameters:: handle – [IN] Handle for the registered interrupt
Returns:: The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

int32_t SDL_DPL_delay(int32_t ndelay)

DPL delay.

This function is used assign delay in the function

Parameters:: ndelay – [IN] delay in microseconds
Returns:: The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

void *SDL_DPL_addrTranslate(uint64_t addr, uint32_t size)

DPL Address translation function.

This function is used by the SDL to get a translation for a 64-bit address to local address space. It is expected that the requested adddress will remain available at the returned address and not be removed.

Parameters:

addr – [IN] Memory address to be translated
size – [IN] Size of the memory

Returns:

The translated address or (-1) for failure.

int32_t SDL_DPL_globalDisableInterrupts(uintptr_t *key)

DPL globally disable interrupts.

This function will disable interrupts globally. Interrupts can be enabled with the globalRestoreInterrupts() function. Usually used for critical sections.

The returned key is used to restore the context once interrupts are restored.

Parameters:: key – [OUT] key to use when restoring interrupts
Returns:: The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

int32_t SDL_DPL_globalRestoreInterrupts(uintptr_t key)

DPL globally enable interrupts.

This function will enable interrupts globally. Usually used for critical sections.

The key is used to restore the context.

Parameters:: key – [IN] key to use when restoring interrupts
Returns:: The SDL error code for the API. If function pointer in interface is NULL: SDL_EBADARGS If other error happened: SDL_EFAIL Success: SDL_PASS

struct SDL_DPL_HwipParams

#include <sdl_dpl.h>

This structure contains the parameters for interrupt registration through the SDL DPL interface.

Public Members

int32_t intNum: Interrupt Vector Id

pSDL_DPL_InterruptCallbackFunction callback: Callback function for the interrupt

uintptr_t callbackArg: Argument passed to the callback function

struct SDL_DPL_Interface

#include <sdl_dpl.h>

This structure contains the pointers for the DPL interfaces provided by the application to SDL_DPL_init.

Public Members

pSDL_DPL_InterruptFunction enableInterrupt: < Pointer to interrupt enable function Pointer to interrupt disable function

pSDL_DPL_InterruptFunction disableInterrupt: Pointer to interrupt registration function

pSDL_DPL_RegisterFunction registerInterrupt: Pointer to inerrupt de-register function

pSDL_DPL_DeregisterFunction deregisterInterrupt: Pointer to delay function

pSDL_DPL_DelayFunction delay: Pointer to global interrupt disable function

pSDL_DPL_globalDisableInterruptsFunction globalDisableInterrupts: Pointer to global interrupt enable function

pSDL_DPL_globalRestoreInterruptsFunction globalRestoreInterrupts: Pointer to address translation function

pSDL_DPL_AddrTranslateFunction addrTranslate