/** @file  ISecureImageParser.idl */

// Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
// All rights reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.

/**
 * The parent/common interface defining the error codes, shared by the Secure Image Parser interfaces.
 */
/** @cond */
interface ISecureImageParserReturnCode{
/** @endcond */

        /**
         * @addtogroup ISecureImageParserReturnCode
         * @{
         */

        /** @cond */
        error IMAGE_NOT_BOUND_TO_REQUESTED_ITEM; /** The image is not bound to the requested binding. Not an error. */

        error IMAGE_BINDING_NOT_SUPPORTED_FOR_REQUESTED_ATTRIBUTE; /** The image (hash table segment metadata version) does not allow binding to the requested item. */
        error IMAGE_NOT_AN_ELF; /** Failed to parse the ELF file. */
        error IMAGE_INCOMPLETE_OR_CORRUPTED; /** Possibly corrupted or incomplete image provided. */
        error IMAGE_HAS_MULTIPLE_HASH_TABLE_SEGMENTS; /** Expecting an image with a single hash table segment. Multiple hash table segments detected. */
        error IMAGE_HASH_TABLE_NOT_FOUND; /** Image is missing a hash table segment. */
        error IMAGE_SEGMENT_INFO_INVALID; /** Failed to get segment info on one of the segments. */
        error HASH_TABLE_SEGMENT_INVALID; /** Failed to parse hash table segment. */
        error HASH_TABLE_SEGMENT_VERSION_UNKNOWN; /** Unknown hash table segment version. */
        error HASH_TABLE_SEGMENT_VERSION_NOT_SUPPORTED; /** Hash table segment version is not supported. */
        error HASH_TABLE_SEGMENT_NO_OEM_METADATA; /** Failed to get the OEM metadata. */
        error HASH_TABLE_SEGMENT_NO_QTI_METADATA; /** Failed to get the QTI metadata. */
        error HASH_TABLE_SEGMENT_NO_COMMON_METADATA; /** Failed to get the common metadata (for MBNv7 images and up). */
        error HASH_TABLE_SEGMENT_METADATA_INVALID; /** Hash Table Segment Metadata is invalid. Possible file corruption. */

        error MEMORY_OBJECT_BINDING_FAILED; /** Failed to bind to a memory object. */
        error MEMORY_OBJECT_MAPPING_FAILED; /** Failed to map a memory object. */
        /** @endcond */

        /** @} */ /* end_addtogroup ISecureImageParserReturnCode */
};

/**
 * Generic interface for extracting hash table segment OEM metadata information from Secboot images.
 * Multiple image formats are accepted(i.e., MBNv6, MBNv7, etc.).
 */
/** @cond */
interface ISecureImageOemMetadataParser: ISecureImageParserReturnCode{
/** @endcond */

        /**
         * @addtogroup ISecureImageOemMetadataParser
         * @{
         */

        /**
         * The version of the interface.
         * Allows a user of the interface to verify if implementation (in TZ) corresponds
         * to the interface file version (i.e., this IDL).
         */
        const uint32 INTERFACE_VERSION = 1;

        /**
         * Returns the interface version implemented by the ISecureImageOemMetadataParser.
         * That is just a convenience method. Interface version mismatch is not a problem with Mink IPC.
         * If a caller asks for a method that is not implemented, Mink provides a "not implemented" error.
         * However, in some cases, that could be desired to know the root cause of the mismatch. For example,
         * to report mismatched interface versions in the log.
         *
         * @param[out] interfaceVersion      The INTERFACE_VERSION (see above) used to implement the TZ service.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getInterfaceVersion(out uint32 interfaceVersion);

        /**
         * Returns an Anti Rollback Version for the provided image file.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] antiRollbackVersion  The Anti Rollback Version version value.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getAntiRollbackVersion(in buffer imageFileContent, out uint32 antiRollbackVersion);

        /**
         * Returns an JTAG ID binding for the provided image file if bound to it. If image is unbound, corresponding
         * error code returned (in that case the value of the jtagId is undefined).
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] jtagId               The JTAG ID binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getJtagIdBinding(in buffer imageFileContent, out uint64 jtagId);

        /**
         * Returns SERIAL NUMBER bindings for the provided image file if bound to it. If image is unbound,
         * corresponding error code returned. On success, the API will return an array of uint64 values.
         * The caller must allocate sufficient buffer for that array. Generically, images bind to 8 or fewer serial
         * numbers.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] serialNumbers        The array of SERIAL NUMBER bindings if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getSerialNumberBindings(in buffer imageFileContent, out uint64[] serialNumbers);

        /**
         * Returns an OEM ID binding for the provided image file if bound to it. If image is unbound,
         * corresponding error code returned.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] oemId                The OEM ID binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getOemIdBinding(in buffer imageFileContent, out uint64 oemId);

        /**
         * Returns an OEM PRODUCT ID binding for the provided image file if bound to it. If image is unbound,
         * corresponding error code returned.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] oemProductId         The OEM PRODUCT ID binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getOemProductIdBinding(in buffer imageFileContent, out uint64 oemProductId);

        /**
         * Returns an OEM LIFECYCLE STATE binding for the provided image file if bound to it.
         * Applies to MBNv7 and newer images only. If image is unbound,
         * corresponding error code returned.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] oemLifecycleState    The OEM LIFECYCLE STATE binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getOemLifecycleStateBinding(in buffer imageFileContent, out uint64 oemLifecycleState);

        /**
        * Returns an Anti Rollback Version for the provided image file.
        *
        * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
        * @param[out] antiRollbackVersion  The Anti Rollback Version version value.
        *
        * @return ISecureImageParserReturnCode return code.
        */
        method getAntiRollbackVersionFromMemObj(in interface imageFileContent, out uint32 antiRollbackVersion);

        /**
         * Returns an JTAG ID binding for the provided image file if bound to it. If image is unbound, corresponding
         * error code returned (in that case the value of the jtagId is undefined).
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
         * @param[out] jtagId               The JTAG ID binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getJtagIdBindingFromMemObj(in interface imageFileContent, out uint64 jtagId);

        /**
         * Returns SERIAL NUMBER bindings for the provided image file if bound to it. If image is unbound,
         * corresponding error code returned. On success, the API will return an array of uint64 values.
         * The caller must allocate sufficient buffer for that array. Generically, images bind to 8 or fewer serial
         * numbers.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
         * @param[out] serialNumbers        The array of SERIAL NUMBER bindings if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getSerialNumberBindingsFromMemObj(in interface imageFileContent, out uint64[] serialNumbers);

        /**
         * Returns an OEM ID binding for the provided image file if bound to it. If image is unbound,
         * corresponding error code returned.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
         * @param[out] oemId                The OEM ID binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getOemIdBindingFromMemObj(in interface imageFileContent, out uint64 oemId);

        /**
         * Returns an OEM PRODUCT ID binding for the provided image file if bound to it. If image is unbound,
         * corresponding error code returned.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
         * @param[out] oemProductId         The OEM PRODUCT ID binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getOemProductIdBindingFromMemObj(in interface imageFileContent, out uint64 oemProductId);

        /**
         * Returns an OEM LIFECYCLE STATE binding for the provided image file if bound to it.
         * Applies to MBNv7 and newer images only. If image is unbound,
         * corresponding error code returned.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
         * @param[out] oemLifecycleState    The OEM LIFECYCLE STATE binding value if the image bound to it.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getOemLifecycleStateBindingFromMemObj(in interface imageFileContent, out uint64 oemLifecycleState);

/** @} */ /* end_addtogroup ISecureImageOemMetadataParser */
};


/**
 * Generic interface for extracting hash table segment QTI metadata information from Secboot images.
 * Multiple image formats are accepted(i.e., MBNv6, MBNv7, etc.).
 */
/** @cond */
interface ISecureImageQtiMetadataParser: ISecureImageParserReturnCode{
/** @endcond */

        /**
         * @addtogroup ISecureImageQtiMetadataParser
         * @{
         */

        /**
         * The version of the interface.
         * Allows a user of the interface to verify if implementation (in TZ) corresponds
         * to the interface file version (i.e., this IDL).
         */
        const uint32 INTERFACE_VERSION = 1;

        /**
         * Returns the interface version implemented by the ISecureImageQtiMetadataParser.
         * That is just a convenience method. Interface version mismatch is not a problem with Mink IPC.
         * If a caller asks for a method that is not implemented, Mink provides a "not implemented" error.
         * However, in some cases, that could be desired to know the root cause of the mismatch. For example,
         * to report mismatched interface versions in the log.
         *
         * @param[out] interfaceVersion      The INTERFACE_VERSION (see above) used to implement the TZ service.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getInterfaceVersion(out uint32 interfaceVersion);

        /**
         * Returns an Anti Rollback Version for the provided image file.
         *
         * @param[in]  imageFileContent     Image file content to parse. Uses buffer and size and accepts smaller files.
         * @param[out] antiRollbackVersion  The Anti Rollback Version version value.
         *
         * @return ISecureImageParserReturnCode return code.
         */
        method getAntiRollbackVersion(in buffer imageFileContent, out uint32 antiRollbackVersion);

        /**
        * Returns an Anti Rollback Version for the provided image file.
        *
        * @param[in]  imageFileContent     Image file content to parse. Uses a memory object interface and accepts any file size.
        * @param[out] antiRollbackVersion  The Anti Rollback Version version value.
        *
        * @return ISecureImageParserReturnCode return code.
        */
        method getAntiRollbackVersionFromMemObj(in interface imageFileContent, out uint32 antiRollbackVersion);



/** @} */ /* end_addtogroup ISecureImageQtiMetadataParser */
};