// Copyright(c) 2018-2020, 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 bitstream.h

 * @brief API for manipulating Green Bitstreams (GBS)

 *

 * GBS files store the AFU logic as well as versioned metadata.

 * These routines parse a disk-resident GBS file, expanding its

 * metadata and loading the GBS logic into memory.

 *

 */

#ifndef __OPAE_BITSTREAM_H__

#define __OPAE_BITSTREAM_H__

#include <stdint.h>

#include <stdbool.h>

#include <opae/types.h>

#define OPAE_LEGACY_BITSTREAM_MAGIC 0x1d1f8680

#pragma pack(push, 1)

/**

 * @deprecated Legacy (pre-6.4.0 BBS) format support.

 */

typedef struct _opae_legacy_bitstream_header {

	uint32_t legacy_magic;

	fpga_guid legacy_pr_ifc_id;

} opae_legacy_bitstream_header;

#pragma pack(pop)

#pragma pack(push, 1)

/**

 * Format of the GBS header.

 */

typedef struct _opae_bitstream_header {

	fpga_guid valid_gbs_guid;	/**< indentifies a GBS file */

	uint32_t metadata_length;	/**< length of metadata in bytes */

	char metadata[1];		/**< GBS metadata (JSON) */

} opae_bitstream_header;

#pragma pack(pop)

/**

 * Memory-resident GBS format.

 *

 * `metadata_version` begins at 1 and increments upward.

 * `parsed_metadata` is the expanded metadata structure.

 *

 * If `metadata_version` is 1, then `parsed_metadata`

 * can be safely typecasted to an `opae_bitstream_metadata_v1 *`.

 */

typedef struct _opae_bitstream_info {

	const char *filename;		/**< location of the file on disk */

	uint8_t *data;			/**< entire GBS file contents */

	size_t data_len;		/**< length in bytes of data */

	uint8_t *rbf_data;		/**< start of AFU logic in data */

	size_t rbf_len;			/**< length of AFU logic in bytes */

	fpga_guid pr_interface_id;	/**< identifies GBS compatibility */

	int metadata_version;		/**< identifies metadata format */

	void *parsed_metadata;		/**< the expanded metadata */

} opae_bitstream_info;

#define OPAE_BITSTREAM_INFO_INITIALIZER \

{ NULL, NULL, 0, NULL, 0, { 0, }, 0, NULL }

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

/**

 * Load a GBS file from disk into memory

 *

 * Used to validate and load a GBS file into its memory-resident format.

 *

 * @param[in] file Location of the GBS file on disk.

 * @param[out] info Storage for the loaded GBS file contents

 *                  and its expanded metadata.

 *

 * @returns FPGA_OK on success. FPGA_INVALID_PARAM if the bitstream

 * format is invalid. FPGA_NO_MEMORY if memory allocation fails.

 * FPGA_EXCEPTION if a metadata parsing error was encountered.

 */

fpga_result opae_load_bitstream(const char *file, opae_bitstream_info *info);

/**

 * @deprecated Determine whether a loaded GBS is in legacy format.

 *

 * Legacy GBS files have no metadata.

 */

bool opae_is_legacy_bitstream(opae_bitstream_info *info);

/**

 * Unload a memory-resident GBS

 *

 * Used to free the resources allocated by `opae_load_bitstream`.

 *

 * @param[in] info The loaded GBS info to be released.

 *

 * @returns FPGA_OK on success. FPGA_INVALID_PARAM if info is NULL.

 * FPGA_EXCEPTION if the metadata version is not supported.

 */

fpga_result opae_unload_bitstream(opae_bitstream_info *info);

#ifdef __cplusplus

}

#endif /* __cplusplus */

#endif /* __OPAE_BITSTREAM_H__ */