// 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 */