cpu_usage.c

Luminary Micro BLDC motor control software

//*****************************************************************************
//
// cpu_usage.c - Routines to determine the CPU utilization.
//
// Copyright (c) 2007-2008 Luminary Micro, Inc.  All rights reserved.
// 
// Software License Agreement
// 
// Luminary Micro, Inc. (LMI) is supplying this software for use solely and
// exclusively on LMI's microcontroller products.
// 
// The software is owned by LMI and/or its suppliers, and is protected under
// applicable copyright laws.  All rights are reserved.  You may not combine
// this software with "viral" open-source software in order to form a larger
// program.  Any use in violation of the foregoing restrictions may subject
// the user to criminal sanctions under applicable laws, as well as to civil
// liability for the breach of the terms and conditions of this license.
// 
// THIS SOFTWARE IS PROVIDED "AS IS".  NO WARRANTIES, WHETHER EXPRESS, IMPLIED
// OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
// LMI SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR
// CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
// 
// This is part of revision 716 of the BLDC motor application.
//
//*****************************************************************************

#include "../../DriverLib/hw_memmap.h"
#include "../../DriverLib/hw_types.h"
#include "../../DriverLib/src/sysctl.h"
#include "../../DriverLib/src/timer.h"
#include "cpu_usage.h"

//*****************************************************************************
//
//! \page cpu_usage_intro Introduction
//!
//! The CPU utilization module uses one of the system timers and peripheral
//! clock gating to determine the percentage of the time that the processor is
//! being clocked.  For the most part, the processor is executing code whenever
//! it is being clocked (exceptions occur when the clocking is being
//! configured, which only happens at startup, and when entering/exiting an
//! interrupt handler, when the processor is performing stacking operations on
//! behalf of the application).
//!
//! The third timer (timer2) is configured to run when the processor is in run
//! mode and to not run when the processor is in sleep mode.  Therefore, the
//! timer will only count when the processor is being clocked.  Comparing the
//! number of clocks the timer counted during a fixed period to the number of
//! clocks in the fixed period provides the percentage utilization.
//!
//! In order for this to be effective, the application must put the processor
//! to sleep when it has no work to do (instead of busy waiting).  If the
//! processor never goes to sleep (either because of a continual stream of work
//! to do or a busy loop), the processor utilization will be reported as 100%.
//!
//! Since deep-sleep mode changes the clocking of the system, the computed
//! processor usage may be incorrect if deep-sleep mode is utilized.  The
//! number of clocks the processor spends in run mode will be properly counted,
//! but the timing period may not be accurate (unless extraordinary
//! measures are taken to ensure timing period accuracy).
//!
//! The accuracy of the computed CPU utilization depends upon the regularity
//! with which CPUUsageTick() is called by the application.  If the CPU usage
//! is constant, but CPUUsageTick() is called sporadically, the reported CPU
//! usage will fluctuate as well despite the fact that the CPU usage is
//! actually constant.
//
//*****************************************************************************

//*****************************************************************************
//
//! \defgroup cpu_usage_api Definitions
//! @{
//
//*****************************************************************************

//*****************************************************************************
//
//! The number of processor clock ticks per timing period.
//
//*****************************************************************************
static unsigned long g_ulCPUUsageTicks;

//*****************************************************************************
//
//! The value of timer two on the previous timing period.  This is used to
//! determine the number of clock ticks counted by the timer during the timing
//! period.
//
//*****************************************************************************
static unsigned long g_ulCPUUsagePrevious;

//*****************************************************************************
//
//! Updates the CPU usage for the new timing period.
//!
//! This function, when called at the end of a timing period, will update the
//! CPU usage.
//!
//! \return Returns the CPU usage percentage as a 16.16 fixed-point value.
//
//*****************************************************************************
unsigned long
CPUUsageTick(void)
{
    unsigned long ulValue, ulUsage;

    //
    // Get the current value of the timer.
    //
    ulValue = TimerValueGet(TIMER2_BASE, TIMER_A);

    //
    // Based on the number of clock ticks accumulated by the timer during the
    // previous timing period, compute the CPU usage as a 16.16 fixed-point
    // value.
    //
    ulUsage = ((((g_ulCPUUsagePrevious - ulValue) * 6400) /
                g_ulCPUUsageTicks) * 1024);

    //
    // Save the previous value of the timer.
    //
    g_ulCPUUsagePrevious = ulValue;

    //
    // Return the new CPU usage value.
    //
    return(ulUsage);
}

//*****************************************************************************
//
//! Initializes the CPU usage measurement module.
//!
//! \param ulRate is the number of times per second that CPUUsageTick() is
//! called.
//!
//! This function prepares the CPU usage measurement module for measuring the
//! CPU usage of the application.
//!
//! \return None.
//
//*****************************************************************************
void
CPUUsageInit(unsigned long ulRate)
{
    //
    // Determine the number of system clocks per measurement period.
    //
    g_ulCPUUsageTicks = SysCtlClockGet() / ulRate;

    //
    // Set the previous value of the timer to the initial timer value.
    //
    g_ulCPUUsagePrevious = 0xffffffff;

    //
    // Enable the third timer while the processor is in run mode, but disable
    // it in sleep mode.  It will therefore count system clocks when the
    // processor is running but not when it is sleeping.
    //
    SysCtlPeripheralEnable(SYSCTL_PERIPH_TIMER2);
    SysCtlPeripheralSleepDisable(SYSCTL_PERIPH_TIMER2);

    //
    // Configure the third timer for 32-bit periodic operation.
    //
    TimerConfigure(TIMER2_BASE, TIMER_CFG_32_BIT_PER);

    //
    // Set the load value for the third timer to the maximum value.
    //
    TimerLoadSet(TIMER2_BASE, TIMER_A, 0xffffffff);

    //
    // Enable the third timer.  It will now count the number of system clocks
    // during which the processor is executing code.
    //
    TimerEnable(TIMER2_BASE, TIMER_A);
}

//*****************************************************************************
//
// Close the Doxygen group.
//! @}
//
//*****************************************************************************