POK

POK: Power OK

Introduction

This device has several internal voltage monitors called Power OK (POK). These monitors can be configured to detect undervoltage (UV) or overvoltage (OV) conditions, and to report errors via ESM. SDL provides the support for programming of the POK modules, including the internal POKs for the POR module. The threshold limits can be configured, and the POK monitoring enabled. Programming is generally done at init time. All POK modules are in the mcu domain.

POK modules are responsible for monitoring and accurately detecting voltage levels. POK modules are capable of monitoring a range of supplies and indicating a failure within the programmable upper and lower threshold limits for the supply being monitored. POKs are used to monitor voltage supply levels with programmable threshold levels. As an example, the POK programmable threshold resolution is 12.5mV for the threshold setting range from 0.475V to 1.35V for under voltage protection.

This module provides the following functionality:

Ability to initialize a POK
Ability to verify written POK configuration
Ability to readback of written configuration

SysConfig Features

None

Features NOT Supported

None

Important Usage Guidelines

None

Example Usage

The following shows an example of SDL POK API usage by the application to set up the POK and usage of the POK APIs. Events can be monitored by enabling the events in the associated ESM instance.

Initialize a POK Instance

.. code:: bash

    int32_t sdlRet;
    SDL_POK_config pokCfg;
    SDL_POK_Inst instance;

    instance = SDL_POR_POKHV_OV_ID;
    pPokCfg.voltDetMode = SDL_PWRSS_SET_OVER_VOLTAGE_DET_ENABLE;
    pPokCfg.trim = 0; // Configure the OV (Over voltage) POK to a small value to force an error
                      // Alternatively, can provide a good value

    sdlRet = SDL_POK_init(instance, &pokCfg);
    if (sdlRet != SDL_PASS)
    {
        UART_printf("SDL_POK_init failed! \n");
    }

    /* If ESM event comes, then Over voltage condition is reached */

Verify the Written Config (can be called after SDL_POK_init)

.. code:: bash

    int32_t ret;

    /* Pass the expected config */
    ret = SDL_POK_verifyConfig(instance, &pokCfg);
    if (ret != SDL_Pass)
    {
        // verification failed
    }

Read back the Static Registers

.. code:: bash

    int32_t ret;
    SDL_POK_staticRegs staticRegs;

    ret = SDL_POK_getStaticRegisters(instance, &staticRegs);
    if (ret != SDL_PASS)
    {
        // failed to get static regs
    }

API Reference

This file contains the prototypes of the APIs present in the device abstraction layer file of POK. This also contains some related macros.

Functions

int32_t SDL_POK_enablePP(SDL_PRG_Inst instance, bool enable)

POK Function to enable or disable ping/pong mode for a specified PRG. Only supported for v1 version of the IP.

Parameters:

instance – Instance of PRG
enable – Enable or disable the ping/pong mode

Returns:

SDL_PASS for success. SDL Error Code for failure.

int32_t SDL_POK_getStaticRegisters(SDL_POK_Inst instance, SDL_POK_staticRegs *pStaticRegs)

POK Function to get the Static Registers. This function reads the values of the static registers such as hysteresis control, voltage detect mode, trim, PORGP and module status.

Parameters:

instance – Instance of POK
pStaticRegs – Pointer to the static registers structure

Returns:

SDL_PASS for success. SDL Error Code for Failure.

int32_t SDL_POK_init(SDL_POK_Inst instance, const SDL_POK_config *pPokCfg)

POK module configuration API.

Parameters:

instance – Instance of POK
pPokCfg – Pointer to the configuration structure

Returns:

SDL_PASS for success. SDL Error Code for Failure.

int32_t SDL_POK_verifyConfig(SDL_POK_Inst instance, const SDL_POK_config *pPokCfg)

POK Function to verify the written configuration. This function checks the provided config against the written config and returns the verification status.

Parameters:

instance – Instance of POK
pPokCfg – Pointer to the configuration structure

Returns:

SDL_PASS if configuration is verified to match. SDL Error Code for Failure.

struct SDL_POK_staticRegs

#include <sdl_pok.h>

POK Static Registers structure.

This structure defines the POK static configuration registers

Public Members

uint8_t hystCtrl: Hysteresis control value

uint8_t hystCtrlOV: Hysteresis control for OV

uint8_t voltDetMode: Voltage Detection Mode value

uint8_t trim: trim value

uint8_t trimOV: trim value for OV

uint8_t deglitch: deglitch value

bool porBGapOK: POR Band Gap OK status

uint8_t porModuleStatus: POR Module Status

Header file containing various enumerations, structure definitions and function declarations for the Power System modules such as POK/POR IP.

POK types

This enumerator defines the possible POK module types

SDL_TYPE_POK: POK type Power System Module

SDL_TYPE_POK_SA: POK_SA type Power System Module

typedef uint8_t SDL_pok_type

POK/POR Deglitch types

This enumerator defines the possible ping-pong control values for the Power Subsystem modules

SDL_PWRSS_DEGLITCH_5US: Deglitch period 5us

SDL_PWRSS_DEGLITCH_10US: Deglitch period 10us

SDL_PWRSS_DEGLITCH_15US: Deglitch period 15us

SDL_PWRSS_DEGLITCH_20US: Deglitch period 20us

SDL_PWRSS_DEGLITCH_GET_VALUE: Get the Deglitch value

SDL_PWRSS_DEGLITCH_NO_ACTION: No update on hysteresis for the module

typedef uint8_t SDL_pwrss_deglitch

POK/POR Ping/Pong types

This enumerator defines the possible deglitch control values for the Power Subsystem modules

SDL_PWRSS_PP_MODE_DISABLE: Ping Pong Disable

SDL_PWRSS_PP_MODE_ENABLE: Ping Pong Enable

SDL_PWRSS_PP_MODE_NO_ACTION: No update on ping pong for the module

typedef uint8_t SDL_pwrss_pp

POK/POR hysteresIs types

This enumerator defines the possible hysteresis control values for the Power Subsystem modules

SDL_PWRSS_SET_HYSTERESIS_DISABLE: Disable hysteresis for the module

SDL_PWRSS_SET_HYSTERESIS_ENABLE: Enable hysteresis for the module

SDL_PWRSS_GET_HYSTERESIS_VALUE: Get hysteresis value for the module

SDL_PWRSS_HYSTERESIS_NO_ACTION: No update on hysteresis for the module

typedef uint8_t SDL_pwrss_hysteresis

POK/POR TRIM values

This enumerator defines the possible trim value for POK/POR modules Any value between 0 through 127 is valid TRIM value

*
*     POK        | Under Voltage   | Over Voltage     |
*                | Detection       | Detection        | Step Resolution
*    ----------- | --------------- | ---------------- | ----------------
*     CORE_POK   | 475mV - 1.35V   |  725mV - 1.65V   | 0.0125V
*     POK1.8     | 1.432V - 2.168V |  1.432V - 2.168V | 0.02V
*     POK3.3     | 2.625V - 3.975V |  2.625V - 3.975V | 0.0375V
*
*

SDL_PWRSS_MAX_TRIM_VALUE: TRIM is 7 bit value, when the trim value is <= to the MAX value, that value would be written to trim register Any other values, would be treated as the command as described below TRIM is 7 bit value, and hence the maximum value is 127

SDL_PWRSS_TRIM_NO_ACTION: No update on trim value read/write for the module

SDL_PWRSS_GET_TRIM_VALUE: Command to read the TRIM value

SDL_PWRSS_INVALID_TRIM_VALUE: Invalid TRIM value

typedef uint8_t SDL_pwrss_trim

POK/POR Voltage detection modes

This enumerator defines the possible values of Voltage Detection modes

SDL_PWRSS_SET_UNDER_VOLTAGE_DET_ENABLE: Enable under voltage detection for the module

SDL_PWRSS_SET_OVER_VOLTAGE_DET_ENABLE: Enable over voltage detection for the module

SDL_PWRSS_SET_PP_VOLTAGE_DET_ENABLE: Enable ping-pong voltage detection for the module

SDL_PWRSS_GET_VOLTAGE_DET_MODE: Get voltage detection for the module

SDL_PWRSS_VOLTAGE_DET_NO_ACTION: No update on voltage detection mode update for the module

typedef uint8_t SDL_pwrss_vd_mode

POK detection status

This enumerator defines the POK Detection status values

SDL_POK_DETECTION_DISABLED: POK Detection disabled

SDL_POK_DETECTION_ENABLED: POK Detection Enabled

typedef uint8_t SDL_POK_detection_status

POK detection values

This enumerator defines the POK Detection values

SDL_POK_DETECTION_DISABLE: POK Detection disabled

SDL_POK_DETECTION_ENABLE: POK Detection Enabled

SDL_POK_DETECTION_NO_ACTION: POK Detection No action

SDL_POK_GET_DETECTION_VALUE: POK Detection get value

typedef uint8_t SDL_POK_detection

POK Enable Selection source Values

This enumerator defines the POK Enable selection source

Selection source values

SDL_POK_ENSEL_HWTIEOFFS: POK enables come from hardware tie offs

SDL_POK_ENSEL_PRG_CTRL: POK enables come from CTRLMMR_WKUP_PRG0_CTRL register

SDL_POK_ENSEL_NO_ACTION: POK enable selection no action

SDL_POK_GET_ENSEL_VALUE: POK enable selection Get value

typedef uint8_t SDL_POK_enSelSrc

POK trim selection values from HHV default or CTRL registers

This enumerator defines the trim selection values

SDL_POR_TRIM_SELECTION_FROM_HHV_DEFAULT: Trim selections for Bandgap and PORs come from HHV defaults

SDL_POR_TRIM_SELECTION_FROM_CTRL_REGS: Trim selections for Bandgap and POKs come from CTRLMMR_WKUP_POR_BANDGAP_CTRL and POR_POKxxx_CTRL registers

SDL_POR_TRIM_SELECTION_NO_CHANGE: Trim selections for Bandgap and POKs No Change

SDL_POR_TRIM_SELECTION_GET_VALUE: Trim Read selections Bandgap and POKs

typedef uint8_t SDL_por_trim_sel

POR Module state values

This enumerator defines the POR Module State

SDL_POR_MODULE_STATUS_FUNCTIONAL_MODE: POR in functional mode

SDL_POR_MODULE_STATUS_RESET_MODE: POR in Reset mode

typedef uint8_t SDL_por_module_status

POK POK ID values

This enumerator defines the Wake up control MMR register

typedef SDL_mcu_ctrl_mmr_cfg0Regs SDL_mcuCtrlRegsBase_t

Functions

int32_t SDL_pok_getPRGInfo(SDL_mcuCtrlRegsBase_t *pBaseAddress, SDL_PRG_Inst instance, SDL_pokPRGInfo_t *pPRGInfo)

void sdlGetErrSig(uint32_t id, SDL_POK_Inst *instance, uint32_t *esm_err_sig_uv, uint32_t *esm_err_sig_ov, bool *usePorCfgFlag)

struct SDL_pokShiftsAndMasks_t

#include <sdl_pok_def.h>

Public Members

uint32_t *pokAddr

uint32_t *pokOVAddr

uint32_t *pokDetAddr

uint32_t *pokEnSelAddr

uint32_t *pokEnPPAddr

uint32_t *deglitchSelAddr

uint32_t pokEnPPMask

uint32_t pokEnPPShift

uint32_t hystMask

uint32_t hystShift

uint32_t hystOVMask

uint32_t hystOVShift

uint32_t vdDetMask

uint32_t vdDetShift

uint32_t vdDetOVMask

uint32_t vdDetOVShift

uint32_t detEnMask

uint32_t detEnShift

uint32_t ovSelMask

uint32_t ovSelShift

uint32_t pokEnSelMask

uint32_t pokEnSelShift

uint32_t trimMask

uint32_t trimShift

uint32_t trimOVMask

uint32_t trimOVShift

uint32_t deglitchSelMask

uint32_t deglitchSelShift

struct SDL_pokPRGInfo_t

#include <sdl_pok_def.h>

Public Members

uint32_t *addr

uint32_t pokEnPPMask

uint32_t pokEnPPShift

struct SDL_POK_config

#include <sdl_pok_def.h>

POK Configuration structure.

This structure contains the POK Control register Configuration

Public Members

SDL_pwrss_hysteresis hystCtrl: hysteresis control

SDL_pwrss_hysteresis hystCtrlOV: hysteresis control - OV

SDL_pwrss_vd_mode voltDetMode: Voltage Detection Mode control

SDL_pwrss_trim trim: POK Trim bits 7 bits wide

SDL_pwrss_trim trimOV: POK Trim bits 7 bits widt for OV

SDL_POK_detection detectionCtrl: POK Detection Enable

SDL_POK_enSelSrc pokEnSelSrcCtrl: POK Enable Source control

SDL_pwrss_deglitch deglitch: Deglitch control

struct SDL_pokVal_t

#include <sdl_pok_def.h>

POK Configuration structure read value.

This structure contains the POK Control register Configuration

Public Members

SDL_pwrss_hysteresis hystCtrl: hysteresis control

SDL_pwrss_hysteresis hystCtrlOV: hysteresis control for OV setting

SDL_pwrss_vd_mode voltDetMode: Voltage Detection Mode control

SDL_pwrss_trim trim: POK Trim bits 7 bits wide

SDL_pwrss_trim trimOV: POK Trim bits for OV - 7 bits wide

SDL_POK_detection_status detectionStatus: POK detection Status

SDL_POK_enSelSrc pokEnSelSrcCtrl: POK Enable Source control

SDL_pwrss_deglitch deglitch: POK Deglitch control

struct SDL_pokPorCfg_t

#include <sdl_pok_def.h>

POK functionality of POR Configuration structure.

This structure contains the configuration for POK functionality of POR Control register

Public Members

bool maskHHVOutputEnable: Mask HHV/SOC_PORz outputs when applying new trim values

SDL_por_trim_sel trim_select: POK Trim selection

struct SDL_pokPorVal_t

#include <sdl_pok_def.h>

POK functionality of POR Value structure.

This structure contains the value for POK functionality of POR Control register

Public Members

bool maskHHVOutputEnable: Mask HHV/SOC_PORz outputs when applying new trim values

SDL_por_trim_sel trim_select: POK Trim selection