// Copyright(c) 2018, Intel Corporation
//
// 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 Intel Corporation  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 fmeinfo.h
 *
 * @brief
 */
#ifndef BMC_H
#define BMC_H

#include <opae/fpga.h>
#include "bmc_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Load Sensor Data Records from the BMC on the FPGA.
 *
 * Query the BMC for descriptions of all sensors it supports.
 *
 * @note This call creates a new SDR object and allocates memory for it. It
 * is the responsibility of the using application to free this memory after use
 * by calling bmcDestroySDRs() for the SDR object.
 *
 * @note Calling this function with a NULL 'records' parameter will return
 * the total number of sensors available in 'num_sensors'.
 *
 * @param[in] token           fpga_token object for device (FPGA_DEVICE type)
 * @param[out] records        bmc_sdr_handle pointer.  Can be NULL
 * @param[inout] num_sensors  The number of sensors available from the BMC
 * @returns                   FPGA_OK on success
 */
fpga_result bmcLoadSDRs(fpga_token token, bmc_sdr_handle *records,
			uint32_t *num_sensors);

/**
 * Free Sensor Data Records memory allocated by bmcLoadSDRs.
 *
 * @note The 'records' value will be set to NULL on success.
 *
 * @param[in] records        bmc_sdr_handle pointer
 * @returns                  FPGA_OK on success
 */
fpga_result bmcDestroySDRs(bmc_sdr_handle *records);

/**
 * Load raw sensor readings from the BMC on the FPGA.
 *
 * Read all the raw sensor values from the BMC.
 *
 * @note This call creates a new Values object and allocates memory for it. It
 * is the responsibility of the using application to free this memory after use
 * by calling bmcDestroySensorValues() for the Values object.
 *
 * @note This call obtains a snapshot of all the sensor readings, providing
 * readings consistent with the time the function was called.
 *
 * @note Calling this function with a NULL 'values' parameter will return
 * the total number of sensor readings available in 'num_values'.
 *
 * @param[in] records         bmc_sdr_handle pointer
 * @param[in] values          bmc_values_handle pointer (can be NULL)
 * @param[inout] num_values   The number of sensor readings available from the
 * BMC
 * @returns                   FPGA_OK on success
 */
fpga_result bmcReadSensorValues(bmc_sdr_handle records,
				bmc_values_handle *values,
				uint32_t *num_values);

/**
 * Free Sensor Values memory allocated by bmcReadSensorValues.
 *
 * @note The 'values' value will be set to NULL on success.
 *
 * @param[in] values         bmc_values_handle pointer
 * @returns                  FPGA_OK on success
 */
fpga_result bmcDestroySensorValues(bmc_values_handle *values);

/**
 * Return a properly scaled value for a sensor.  The value will be appropriate
 * for comparison or printing in the units specified for the sensor.
 *
 * @note The raw value of the sensor (for linear sensors) is calculated using
 * the "Mx + B * 10^exp" formula and is scaled by the specified result exponent.
 *
 * @note The accuracy and tolerance values are sensor-dependent and may not
 * be supplied.  If they are not supplied, the default value is zero for both.
 * Tolerance is in number of 1/2 raw sensor reading increments.  The accuracy
 * is given in units of 1/100%, scaled up by the accuracy exponent (i.e.,
 * *10^exp).
 *
 * @param[in] values          bmc_values_handle
 * @param[in] sensor_number   The sensor of interest
 * @param[out] is_valid       This sensor's reading is unavailable if 0
 * @param[out] value          The scaled value of this sensor's reading
 * @returns                   FPGA_OK on success
 */
fpga_result bmcGetSensorReading(bmc_values_handle values,
				uint32_t sensor_number, uint32_t *is_valid,
				double *value);

/**
 * Return a list of sensors whose thresholds are reported as exceeded by the
 * BMC.
 *
 * @note This call allocates an array of tripped_thresholds structures of
 * .size 'num_tripped'. It is the responsibility of the using application to
 * free this memory after use by calling bmcDestroyTripped() for the 'tripped'
 * object.
 *
 * @param[in] values          bmc_values_handle
 * @param[in] tripped         Address where a pointer to an array of
 *                            tripped_thresholds structs is stored
 *                            (may be NULL)
 * @param[out] num_tripped    The number of sensors tripped
 * @returns                   FPGA_OK on success
 */
fpga_result bmcThresholdsTripped(bmc_values_handle values,
				 tripped_thresholds **tripped,
				 uint32_t *num_tripped);

/**
 * Free Sensor Values memory allocated by bmcThresholdsTripped.
 *
 * @note The 'tripped' value will be set to NULL on success.
 *
 * @param[in] tripped        bmc_values_handle pointer
 * @returns                  FPGA_OK on success
 */
fpga_result bmcDestroyTripped(tripped_thresholds *tripped);

/**
 * Return detailed information regarding a sensor.
 *
 * @param[in] values          bmc_values_handle
 * @param[in] sensor_number   The sensor of interest
 * @param[out] details        A pointer to a sdr_details structure
 * @returns                   FPGA_OK on success
 */
fpga_result bmcGetSDRDetails(bmc_values_handle values, uint32_t sensor_number,
			     sdr_details *details);

/**
 * Return BMC reported microcontroller version.
 *
 * @param[in] token           fpga_token object for device (FPGA_DEVICE type)
 * @param[out] version        BMC microcontroller version
 * @returns                   FPGA_OK on success
 */
fpga_result bmcGetFirmwareVersion(fpga_token token, uint32_t *version);

/**
 * Return BMC reported last powerdown cause.
 *
 * @param[in] token           fpga_token object for device (FPGA_DEVICE type)
 * @param[out] cause          String describing last powerdown cause
 * @returns                   FPGA_OK on success
 */
fpga_result bmcGetLastPowerdownCause(fpga_token token, char **cause);

/**
 * Return BMC reported last reset cause.
 *
 * @param[in] token           fpga_token object for device (FPGA_DEVICE type)
 * @param[out] cause          String describing last reset cause
 * @returns                   FPGA_OK on success
 */
fpga_result bmcGetLastResetCause(fpga_token token, char **cause);

/**
 * Set BMC threshold values for a sensor.
 *
 * @param[in] sdr_h    bmc_sdr_handle
 * @param[in] sensor   The sensor of interest
 * @param[in] thresh   A pointer to a list of thresholds to set
 * @returns            FPGA_OK on success
 */
fpga_result bmcSetHWThresholds(bmc_sdr_handle sdr_h, uint32_t sensor,
			       threshold_list *thresh);


#ifdef __cplusplus
}
#endif

#endif /* !BMC_H */