ICM Interface

Driver API for ICM (plib_icm.h) More...

Content
	ICM Peripheral Library API

Description

Driver API for ICM (plib_icm.h)

Usage Example

The following example demonstrates typical usage of the ICM peripheral:

/*******************************************************************************
* Copyright © 2026 Microchip Technology Inc. and its subsidiaries.
*
* Subject to your compliance with these terms, you may use Microchip software
* and any derivatives exclusively with Microchip products. It is your
* responsibility to comply with third party license terms applicable to your
* use of third party software (including open source software) that may
* accompany Microchip software.
*
* THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER
* EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED
* WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A
* PARTICULAR PURPOSE.
*
* IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE,
* INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND
* WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS
* BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE
* FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN
* ANY WAY RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
* THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
 *******************************************************************************/
/*******************************************************************************
* @file configure_icm.c
*
* @brief Example ICM configuration recipe: monitor one memory region with SHA-256.
*
* @details Demonstrates the peripheral-clock-enable/ICM_ResetSoftware/ICM_SetGlobalConfig/
*          ICM_SetDescriptorAddress/ICM_SetHashAddress/ICM_ConfigureRegion/
*          ICM_SetCallbackHandler/ICM_EnableInterrupt/ICM_EnableRegionMonitoring/
*          ICM_Enable call sequence needed to watch a single memory region for
*          tampering. Intended to be copied and adapted by an application, not
*          used as-is in production.
 *******************************************************************************/
#include <string.h>
#include "plib_icm.h"
 
/* Descriptor area must be 64-byte aligned, hash area 128-byte aligned. */
static _Alignas(64) uint32_t icmDescriptorArea[4];
static _Alignas(128) uint32_t icmHashArea[8];
 
/* Placeholder data being protected by this demo; replace with the real
 * region (e.g. a flash image or a critical RAM structure) an application
 * needs to monitor. */
static _Alignas(4) uint32_t icmMonitoredData[16];
 
static ICM_REGION_CONFIG_T icmRegion0;
 
/* callback/context are registered before ICM_Enable() below, so the region's
 * real event handler is already in place before any interrupt can fire -
 * avoiding a window where an event would be serviced by no handler at all. */
int32_t configure_icm_region_monitor(IcmCallback_t callback, const void *context)
{
    (void)memset(&icmRegion0, 0, sizeof(icmRegion0));
    icmRegion0.start_addr = (uint32_t)icmMonitoredData;
    icmRegion0.algo       = ICM_RCFG_ALGO(ICM_RCFG_ALGO_SHA256_Val);
    icmRegion0.trsize     = ICM_RCTRL_TRSIZE(0U);   /* 1 block of 512 bits */
    icmRegion0.wrap       = ICM_RCFG_WRAP_Msk;       /* re-enter monitoring after the first pass */
    /* rhien, dmien, eom and cdwbn are left 0 on purpose: RHIEN/DMIEN are
     * *disable* bits (0 = interrupt stays enabled), so leaving them clear is
     * what enables ICM_ISR.RHC/RDM for this region. ICM_CFG.ASCD (below)
     * also requires eom and cdwbn to start cleared. The ICM then writes the
     * baseline digest once, and because wrap=1 it automatically switches to
     * continuous compare mode afterwards, raising RDM on any later mismatch. */
 
    /* Enable the ICM peripheral clock before touching any ICM_REGS field. */
#if (ICM_CLOCK_ID < 32U)
    PMC_REGS->PMC_PCER0 = (1U << ICM_CLOCK_ID);
#else
    PMC_REGS->PMC_PCER1 = (1U << ((uint32_t)ICM_CLOCK_ID - 32U));
#endif
 
    ICM_ResetSoftware();
 
    /* ualgo/uihash bits are left clear (UIHASH=0): the ICM then derives the
     * initial hash value from the standard itself, and the monitored
     * algorithm is taken solely from each region's own ICM_RCFG.ALGO field
     * (icmRegion0.algo above, set to SHA-256). ualgo only has an effect when
     * uihash=1, i.e. when supplying a non-standard programmable initial hash
     * value. */
    ICM_SetGlobalConfig(ICM_CFG_DUALBUFF_Msk |
                         ICM_CFG_BBC(2U)     |
                         ICM_CFG_ASCD_Msk);   /* baseline once, then auto-compare continuously */
 
    if (!ICM_SetDescriptorAddress((uint32_t)icmDescriptorArea))
    {
        return -1;
    }
 
    if (!ICM_SetHashAddress((uint32_t)icmHashArea))
    {
        return -1;
    }
 
    if (!ICM_ConfigureRegion(0U, &icmRegion0))
    {
        return -1;
    }
 
    ICM_SetCallbackHandler(callback, context);
    ICM_EnableInterrupt(ICM_INTERRUPT_RHC, 0U);
    ICM_EnableInterrupt(ICM_INTERRUPT_RDM, 0U);
 
    /* Region monitoring is active by default after reset (ICM_CTRL.RMEN is
     * only needed to re-activate a region previously stopped with RMDIS);
     * this call is here to make the intent explicit. */
    if (!ICM_EnableRegionMonitoring(0U))
    {
        return -1;
    }
 
    /* Nothing is monitored until ICM_CTRL.ENABLE is written, so this must be
     * the last step, once the descriptors and interrupts are all in place. */
    ICM_Enable();
 
    return 0;
}