/*********************************************************************************************************
 *  ------------------------------------------------------------------------------------------------------
 *  file description
 *  ------------------------------------------------------------------------------------------------------
 *         \file  cpul.h
 *         \unit  cpul
 *        \brief  This is a simple cpuload module for C language
 *       \author  Lamdonn
 *      \version  v1.0.0
 *      \license  GPL-2.0
 *    \copyright  Copyright (C) 2023 Lamdonn.
 ********************************************************************************************************/
#ifndef __cpul_H
#define __cpul_H

#include "stdint.h"

/* Version infomation */
#define CPUL_V_MAJOR                        0
#define CPUL_V_MINOR                        1
#define CPUL_V_PATCH                        0

#define CPUL_GEN_BSIZE                      4

#define CPUL_E_OK                           0  // Success
#define CPUL_E_INVALID                      1  // Invalid `CPUL` pointer
#define CPUL_E_RAW                          2  // Invalid raw function
#define CPUL_E_PARA                         3  // Invalid parameter
#define CPUL_E_NTEST                        4  // CPUL load testing has not started
#define CPUL_E_OVER                         5  // CPUL load exceeds range

typedef uint16_t (*cpul_raw_t)(uint8_t coreid); // Type definition for the raw CPUL load function

/**
 * \brief Structure to control CPUL load parameters.
 */
typedef struct 
{
    uint32_t refine;                        ///< Refined load value
    uint16_t cload;                         ///< Current load value
    uint16_t tload;                         ///< Target load value
} CPUL_CTRL;

/**
 * \brief Structure to represent a CPU Load Manager.
 */
typedef struct 
{
    uint8_t coreid;                         ///< Core ID
    cpul_raw_t raw;                         ///< Pointer to the raw CPUL load function
    uint32_t resolution;                    ///< Resolution of the load control
    CPUL_CTRL ctrl;                         ///< Control structure for CPUL management
} CPUL;

/**
 * \brief Initialize the CPUL instance.
 * 
 * This function initializes the CPUL structure to default values
 * and checks for valid pointers.
 * 
 * \param[in] cpul: Pointer to the CPUL instance.
 * \return Returns CPUL_E_OK on success, otherwise an error code.
 */
int cpul_init(CPUL *cpul);

/**
 * \brief Get the current CPU load.
 * 
 * This function retrieves the current load from the CPUL instance
 * and checks for validity of parameters and state.
 * 
 * \param[in] cpul: Pointer to the CPUL instance.
 * \param[out] load: Pointer to store the current load value.
 * \return Returns CPUL_E_OK on success, otherwise an error code.
 */
int cpul_get(CPUL *cpul, uint16_t *load);

/**
 * \brief Set the target CPU load.
 * 
 * This function sets the target load for the CPUL instance and checks for valid parameters.
 * 
 * \param[in] cpul: Pointer to the CPUL instance.
 * \param[in] load: Target load value to set.
 * \return Returns CPUL_E_OK on success, otherwise an error code.
 */
int cpul_set(CPUL *cpul, uint16_t load);

/**
 * \brief Execute a CPUL management task.
 * 
 * This function executes a task to manage the CPU load based on
 * the current and target load values.
 * 
 * \param[in] cpul: Pointer to the CPUL instance.
 * \return Returns CPUL_E_OK on success, otherwise an error code.
 */
int cpul_task(CPUL *cpul);

#endif