dl_trng.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       dl_trng.h
 *  @brief      True Random Number Generator (TRNG) Driver Library
 *  @defgroup   TRNG True Random Number Generator (TRNG)
 *
 *  @anchor ti_dl_dl_m0p_trng_Overview
 *  # Overview
 *
 *  The True Random Number Generator Driver Library allows full configuration of
 *  the MSPM0 TRNG module.
 *  The true random number generator (TRNG) block is an entropy source which
 *  can be used to generate random bit sequences.
 *
 *  <hr>
 ******************************************************************************
 */
#ifndef ti_dl_dl_trng__include
#define ti_dl_dl_trng__include

#include <stdbool.h>
#include <stdint.h>

#include <ti/devices/msp/msp.h>
#include <ti/driverlib/dl_common.h>

#ifdef __MSPM0_HAS_TRNG__

#ifdef __cplusplus
extern "C" {
#endif

/* clang-format off */

#define DL_TRNG_INTERRUPT_HEALTH_FAIL_EVENT   (TRNG_IMASK_IRQ_HEALTH_FAIL_MASK)

#define DL_TRNG_INTERRUPT_CMD_DONE_EVENT         (TRNG_IMASK_IRQ_CMD_DONE_MASK)

#define DL_TRNG_INTERRUPT_CMD_FAIL_EVENT         (TRNG_IMASK_IRQ_CMD_FAIL_MASK)

#define DL_TRNG_INTERRUPT_CAPTURE_RDY_EVENT  (TRNG_IMASK_IRQ_CAPTURED_RDY_MASK)

#define DL_TRNG_DIGITAL_HEALTH_TEST_SUCCESS                              (0xFF)

#define DL_TRNG_ANALOG_HEALTH_TEST_SUCCESS                                (0x1)

/* clang-format on */

typedef enum {
    DL_TRNG_IIDX_HEALTH_FAIL = TRNG_IIDX_STAT_IRQ_HEALTH_FAIL,
    DL_TRNG_IIDX_CMD_DONE = TRNG_IIDX_STAT_IRQ_CMD_DONE,
    DL_TRNG_IIDX_CMD_FAIL = TRNG_IIDX_STAT_IRQ_CMD_FAIL,
    DL_TRNG_IIDX_CAPTURED_READY = TRNG_IIDX_STAT_IRQ_CAPTURED_RDY,
} DL_TRNG_IIDX;

typedef enum {
    DL_TRNG_DECIMATION_RATE_1 = 0x0,
    DL_TRNG_DECIMATION_RATE_2 = 0x1,
    DL_TRNG_DECIMATION_RATE_3 = 0x2,
    DL_TRNG_DECIMATION_RATE_4 = 0x3,
    DL_TRNG_DECIMATION_RATE_5 = 0x4,
    DL_TRNG_DECIMATION_RATE_6 = 0x5,
    DL_TRNG_DECIMATION_RATE_7 = 0x6,
    DL_TRNG_DECIMATION_RATE_8 = 0x7,
} DL_TRNG_DECIMATION_RATE;

typedef enum {
    DL_TRNG_CMD_PWROFF = TRNG_CTL_CMD_PWR_OFF,
    DL_TRNG_CMD_TEST_DIG = TRNG_CTL_CMD_PWRUP_DIG,
    DL_TRNG_CMD_TEST_ANA = TRNG_CTL_CMD_PWRUP_ANA,
    DL_TRNG_CMD_NORM_FUNC = TRNG_CTL_CMD_NORM_FUNC,
} DL_TRNG_CMD;

typedef enum {
    DL_TRNG_CLOCK_DIVIDE_1 = TRNG_CLKDIVIDE_RATIO_DIV_BY_1,
    DL_TRNG_CLOCK_DIVIDE_2 = TRNG_CLKDIVIDE_RATIO_DIV_BY_2,
    DL_TRNG_CLOCK_DIVIDE_4 = TRNG_CLKDIVIDE_RATIO_DIV_BY_4,
    DL_TRNG_CLOCK_DIVIDE_6 = TRNG_CLKDIVIDE_RATIO_DIV_BY_6,
    DL_TRNG_CLOCK_DIVIDE_8 = TRNG_CLKDIVIDE_RATIO_DIV_BY_8,
} DL_TRNG_CLOCK_DIVIDE;

typedef enum {
    DL_TRNG_STATE_OFF = 0x0,
    DL_TRNG_STATE_PWRUP_ES = 0x1,
    DL_TRNG_STATE_NORM_FUNC = 0x3,
    DL_TRNG_STATE_TEST_DIG = 0x7,
    DL_TRNG_STATE_TEST_ANA = 0xB,
    DL_TRNG_STATE_ERROR = 0xA,
    DL_TRNG_STATE_PWRDOWN = 0x2,
} DL_TRNG_STATE;

typedef struct {
    uint32_t controlWord;
    uint32_t clockDivider;
    uint32_t interruptMask;
    bool backupRdy;
} DL_TRNG_backupConfig;

__STATIC_INLINE void DL_TRNG_enablePower(TRNG_Regs *trng)
{
    trng->GPRCM.PWREN = TRNG_PWREN_KEY_UNLOCK_W | TRNG_PWREN_ENABLE_ENABLE;
}

__STATIC_INLINE void DL_TRNG_disablePower(TRNG_Regs *trng)
{
    trng->GPRCM.PWREN = TRNG_PWREN_KEY_UNLOCK_W | TRNG_PWREN_ENABLE_DISABLE;
}

__STATIC_INLINE DL_TRNG_CLOCK_DIVIDE DL_TRNG_getClockDivider(TRNG_Regs *trng)
{
    return (DL_TRNG_CLOCK_DIVIDE) trng->CLKDIVIDE;
}

__STATIC_INLINE void DL_TRNG_setClockDivider(
    TRNG_Regs *trng, DL_TRNG_CLOCK_DIVIDE clockDivider)
{
    trng->CLKDIVIDE = (uint32_t) clockDivider;
}

__STATIC_INLINE void DL_TRNG_reset(TRNG_Regs *trng)
{
    trng->GPRCM.RSTCTL =
        TRNG_RSTCTL_RESETASSERT_ASSERT | TRNG_RSTCTL_KEY_UNLOCK_W;
}

__STATIC_INLINE bool DL_TRNG_isReset(TRNG_Regs *trng)
{
    return (trng->GPRCM.STAT & TRNG_GPRCM_STAT_RESETSTKY_MASK) ==
           TRNG_GPRCM_STAT_RESETSTKY_RESET;
}

__STATIC_INLINE bool DL_TRNG_isCaptureReady(TRNG_Regs *trng)
{
    return ((trng->CPU_INT.RIS & TRNG_RIS_IRQ_CAPTURED_RDY_MASK)) ==
           TRNG_RIS_IRQ_CAPTURED_RDY_SET;
}

__STATIC_INLINE bool DL_TRNG_isCommandDone(TRNG_Regs *trng)
{
    return ((trng->CPU_INT.RIS & TRNG_RIS_IRQ_CMD_DONE_MASK)) ==
           TRNG_RIS_IRQ_CMD_DONE_SET;
}

__STATIC_INLINE bool DL_TRNG_isCommandFail(TRNG_Regs *trng)
{
    return ((trng->CPU_INT.RIS & TRNG_RIS_IRQ_CMD_FAIL_MASK)) ==
           TRNG_RIS_IRQ_CMD_FAIL_SET;
}

__STATIC_INLINE bool DL_TRNG_isHealthTestFail(TRNG_Regs *trng)
{
    return ((trng->CPU_INT.RIS & TRNG_RIS_IRQ_HEALTH_FAIL_MASK)) ==
           TRNG_RIS_IRQ_HEALTH_FAIL_SET;
}

__STATIC_INLINE void DL_TRNG_setDecimationRate(
    TRNG_Regs *trng, DL_TRNG_DECIMATION_RATE decimationRate)
{
    DL_Common_updateReg(&trng->CTL,
        ((uint32_t) decimationRate << TRNG_CTL_DECIM_RATE_OFS),
        TRNG_CTL_DECIM_RATE_MASK);
}

__STATIC_INLINE DL_TRNG_DECIMATION_RATE DL_TRNG_getDecimationRate(
    TRNG_Regs *trng)
{
    uint32_t decimationRate =
        ((trng->CTL & TRNG_CTL_DECIM_RATE_MASK) >> TRNG_CTL_DECIM_RATE_OFS);

    return (DL_TRNG_DECIMATION_RATE)(decimationRate);
}

__STATIC_INLINE uint8_t DL_TRNG_getDigitalHealthTestResults(TRNG_Regs *trng)
{
    return (uint8_t)(trng->TEST_RESULTS & TRNG_TEST_RESULTS_DIG_TEST_MASK);
}

__STATIC_INLINE uint8_t DL_TRNG_getAnalogHealthTestResults(TRNG_Regs *trng)
{
    return (uint8_t)((trng->TEST_RESULTS & TRNG_TEST_RESULTS_ANA_TEST_MASK) >>
                     TRNG_TEST_RESULTS_ANA_TEST_OFS);
}

__STATIC_INLINE uint32_t DL_TRNG_getCurrentState(TRNG_Regs *trng)
{
    return ((trng->STAT & TRNG_STAT_FSM_STATE_MASK)) >>
           TRNG_STAT_FSM_STATE_OFS;
}

__STATIC_INLINE uint32_t DL_TRNG_getIssuedCommand(TRNG_Regs *trng)
{
    return ((trng->STAT & TRNG_STAT_ISSUED_CMD_MASK)) >>
           TRNG_STAT_ISSUED_CMD_OFS;
}

__STATIC_INLINE bool DL_TRNG_isRepetitionTestFail(TRNG_Regs *trng)
{
    return ((trng->STAT & TRNG_STAT_REP_FAIL_MASK)) == TRNG_STAT_REP_FAIL_MASK;
}

__STATIC_INLINE bool DL_TRNG_isAdaptiveTestFail(TRNG_Regs *trng)
{
    return ((trng->STAT & TRNG_STAT_ADAP_FAIL_MASK)) ==
           TRNG_STAT_ADAP_FAIL_MASK;
}

__STATIC_INLINE void DL_TRNG_enableInterrupt(
    TRNG_Regs *trng, uint32_t interruptMask)
{
    trng->CPU_INT.IMASK |= interruptMask;
}

__STATIC_INLINE void DL_TRNG_disableInterrupt(
    TRNG_Regs *trng, uint32_t interruptMask)
{
    trng->CPU_INT.IMASK &= ~interruptMask;
}

__STATIC_INLINE uint32_t DL_TRNG_getEnabledInterrupts(
    TRNG_Regs *trng, uint32_t interruptMask)
{
    return trng->CPU_INT.IMASK & interruptMask;
}

__STATIC_INLINE uint32_t DL_TRNG_getEnabledInterruptStatus(
    TRNG_Regs *trng, uint32_t interruptMask)
{
    return (trng->CPU_INT.MIS & interruptMask);
}

__STATIC_INLINE uint32_t DL_TRNG_getRawInterruptStatus(
    TRNG_Regs *trng, uint32_t interruptMask)
{
    return trng->CPU_INT.RIS & interruptMask;
}

__STATIC_INLINE DL_TRNG_IIDX DL_TRNG_getPendingInterrupt(TRNG_Regs *trng)
{
    return (DL_TRNG_IIDX) trng->CPU_INT.IIDX;
}

__STATIC_INLINE void DL_TRNG_clearInterruptStatus(
    TRNG_Regs *trng, uint32_t interruptMask)
{
    trng->CPU_INT.ICLR = interruptMask;
}

__STATIC_INLINE void DL_TRNG_sendCommand(TRNG_Regs *trng, DL_TRNG_CMD cmd)
{
    DL_Common_updateReg(&trng->CTL, (uint32_t) cmd, TRNG_CTL_CMD_MASK);
}

__STATIC_INLINE uint32_t DL_TRNG_getCapture(TRNG_Regs *trng)
{
    return trng->DATA_CAPTURE;
}

bool DL_TRNG_saveConfiguration(TRNG_Regs *trng, DL_TRNG_backupConfig *ptr);

bool DL_TRNG_restoreConfiguration(TRNG_Regs *trng, DL_TRNG_backupConfig *ptr);

#ifdef __cplusplus
}
#endif

#endif /* __MSPM0_HAS_TRNG__ */

#endif /* ti_dl_dl_trng__include */