From 21bd495843a022beb50dc93210c51cf9586553c9 Mon Sep 17 00:00:00 2001 From: Feng Tian Date: Wed, 13 May 2015 08:35:55 +0000 Subject: [PATCH] MdePkg: Fix EOL to be DOS format. Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Feng Tian git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@17429 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/BlockIoCrypto.h | 1060 ++++++------- MdePkg/Include/Protocol/NvmExpressPassthru.h | 572 +++---- MdePkg/Include/Protocol/SmartCardEdge.h | 1478 +++++++++--------- MdePkg/Include/Protocol/SmartCardReader.h | 652 ++++---- MdePkg/Include/Protocol/UsbFunctionIo.h | 1366 ++++++++-------- 5 files changed, 2564 insertions(+), 2564 deletions(-) diff --git a/MdePkg/Include/Protocol/BlockIoCrypto.h b/MdePkg/Include/Protocol/BlockIoCrypto.h index 2cc60b8a13..40124010bc 100644 --- a/MdePkg/Include/Protocol/BlockIoCrypto.h +++ b/MdePkg/Include/Protocol/BlockIoCrypto.h @@ -1,530 +1,530 @@ -/** @file - The UEFI Inline Cryptographic Interface protocol provides services to abstract - access to inline cryptographic capabilities. - - Copyright (c) 2015, Intel Corporation. All rights reserved.
- This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef __BLOCK_IO_CRYPTO_H__ -#define __BLOCK_IO_CRYPTO_H__ - -#include - -#define EFI_BLOCK_IO_CRYPTO_PROTOCOL_GUID \ - { \ - 0xa00490ba, 0x3f1a, 0x4b4c, {0xab, 0x90, 0x4f, 0xa9, 0x97, 0x26, 0xa1, 0xe8} \ - } - -typedef struct _EFI_BLOCK_IO_CRYPTO_PROTOCOL EFI_BLOCK_IO_CRYPTO_PROTOCOL; - -/// -/// The struct of Block I/O Crypto Token. -/// -typedef struct { - // - // If Event is NULL, then blocking I/O is performed. If Event is not NULL and - // non-blocking I/O is supported, then non-blocking I/O is performed, and - // Event will be signaled when the read request is completed and data was - // decrypted (when Index was specified). - // - EFI_EVENT Event; - // - // Defines whether or not the signaled event encountered an error. - // - EFI_STATUS TransactionStatus; -} EFI_BLOCK_IO_CRYPTO_TOKEN; - - -/** - Reset the block device hardware. - - The Reset() function resets the block device hardware. - - As part of the initialization process, the firmware/device will make a quick but - reasonable attempt to verify that the device is functioning. - - If the ExtendedVerificationflag is TRUE the firmware may take an extended amount - of time to verify the device is operating on reset. Otherwise the reset operation - is to occur as quickly as possible. - - The hardware verification process is not defined by this specification and is left - up to the platform firmware or driver to implement. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[in] ExtendedVerification Indicates that the driver may perform a more exhausive - verfication operation of the device during reset. - - @retval EFI_SUCCESS The block device was reset. - @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could - not be reset. - @retval EFI_INVALID_PARAMETER This is NULL. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_RESET) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - IN BOOLEAN ExtendedVerification - ); - -/** - Get the capabilities of the underlying inline cryptographic interface. - - The GetCapabilities() function determines whether pre-OS controllable inline crypto - is supported by the system for the current disk and, if so, returns the capabilities - of the crypto engine. - - The caller is responsible for providing the Capabilities structure with a sufficient - number of entries. - - If the structure is too small, the EFI_BUFFER_TOO_SMALL error code is returned and the - CapabilityCount field contains the number of entries needed to contain the capabilities. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[out] Capabilities Pointer to the EFI_BLOCK_IO_CRYPTO_CAPABILITIES structure. - - @retval EFI_SUCCESS The ICI is ready for use. - @retval EFI_BUFFER_TOO_SMALL The Capabilities structure was too small. The number of - entries needed is returned in the CapabilityCount field - of the structure. - @retval EFI_NO_RESPONSE No response was received from the ICI. - @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER Capabilities is NULL. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_GET_CAPABILITIES) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - OUT EFI_BLOCK_IO_CRYPTO_CAPABILITIES *Capabilities - ); - -/** - Set the configuration of the underlying inline cryptographic interface. - - The SetConfiguration() function allows the user to set the current configuration of the - inline cryptographic interface and should be called before attempting any crypto operations. - - This configures the configuration table entries with algorithms, key sizes and keys. Each - configured entry can later be referred to by index at the time of storage transaction. - - The configuration table index will refer to the combination ofKeyOwnerGuid, Algorithm, and - CryptoKey. - - KeyOwnerGuid identifies the component taking ownership of the entry. It helps components to - identify their own entries, cooperate with other owner components, and avoid conflicts. This - Guid identifier is there to help coordination between cooperating components and not a security - or synchronization feature. The Nil GUID can be used by a component to release use of entry - owned. It is also used to identify potentially available entries (see GetConfiguration). - - CryptoKey specifies algorithm-specific key material to use within parameters of selected crypto - capability. - - This function is called infrequently typically once, on device start, before IO starts. It - can be called at later times in cases the number of keysused on the drive is higher than what - can be configured at a time or a new key has to be added. - - Components setting or changing an entry or entries for a given index or indices must ensure - that IO referencing affected indices is temporarily blocked (run-down) at the time of change. - - Indices parameters in each parameter table entry allow to set only a portion of the available - table entries in the crypto module anywhere from single entry to entire table supported. - - If corresponding table entry or entries being set are already in use by another owner the call - should be failed and none of the entries should be modified. The interface implementation must - enforce atomicity of this operation (should either succeed fully or fail completely without - modifying state). - - Note that components using GetConfiguration command to discover available entries should be - prepared that by the time of calling SetConfiguration the previously available entry may have - become occupied. Such components should be prepared to re-try the sequence of operations. - - Alternatively EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be used to have the implementation discover - and allocate available,if any, indices atomically. - - An optional ResultingTable pointer can be provided by the caller to receive the newly configured - entries. The array provided by the caller must have at least ConfigurationCount of entries. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[in] ConfigurationCount Number of entries being configured with this call. - @param[in] ConfigurationTable Pointer to a table used to populate the configuration table. - @param[out] ResultingTable Optional pointer to a table that receives the newly configured - entries. - - @retval EFI_SUCCESS The ICI is ready for use. - @retval EFI_NO_RESPONSE No response was received from the ICI. - @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER ConfigurationTable is NULL. - @retval EFI_INVALID_PARAMETER ConfigurationCount is 0. - @retval EFI_OUT_OF_RESOURCES Could not find the requested number of available entries in the - configuration table. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_SET_CONFIGURATION) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - IN UINT64 ConfigurationCount, - IN EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY *ConfigurationTable, - OUT EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY *ResultingTable OPTIONAL - ); - - -/** - Get the configuration of the underlying inline cryptographic interface. - - The GetConfiguration() function allows the user to get the configuration of the inline - cryptographic interface. - - Retrieves, entirely or partially, the currently configured key table. Note that the keys - themselves are not retrieved, but rather just indices, owner GUIDs and capabilities. - - If fewer entries than specified by ConfigurationCount are returned, the Index field of the - unused entries is set to EFI_BLOCK_IO_CRYPTO_INDEX_ANY. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[in] StartIndex Configuration table index at which to start the configuration - query. - @param[in] ConfigurationCount Number of entries to return in the response table. - @param[in] KeyOwnerGuid Optional parameter to filter response down to entries with a - given owner. A pointer to the Nil value can be used to return - available entries. Set to NULL when no owner filtering is required. - @param[out] ConfigurationTable Table of configured configuration table entries (with no CryptoKey - returned): configuration table index, KeyOwnerGuid, Capability. - Should have sufficient space to store up to ConfigurationCount - entries. - - @retval EFI_SUCCESS The ICI is ready for use. - @retval EFI_NO_RESPONSE No response was received from the ICI. - @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER Configuration table is NULL. - @retval EFI_INVALID_PARAMETER StartIndex is out of bounds. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_GET_CONFIGURATION) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - IN UINT64 StartIndex, - IN UINT64 ConfigurationCount, - IN EFI_GUID *KeyOwnerGuid OPTIONAL, - OUT EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY *ConfigurationTable -); - -/** - Reads the requested number of blocks from the device and optionally decrypts - them inline. - - TheReadExtended() function allows the caller to perform a storage device read - operation. The function reads the requested number of blocks from the device - and then if Index is specified decrypts them inline. All the blocks are read - and decrypted (if decryption requested), or an error is returned. - - If there is no media in the device, the function returns EFI_NO_MEDIA. If the - MediaId is not the ID for the current media in the device, the function returns - EFI_MEDIA_CHANGED. - - If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking - I/O is being used, the Event associated with this request will not be signaled. - - In addition to standard storage transaction parameters (LBA, IO size, and buffer), - this command will also specify a configuration table Index and CryptoIvInput - when data has to be decrypted inline by the controller after being read from - the storage device. If an Index parameter is not specified, no decryption is - performed. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[in] MediaId The media ID that the read request is for. - @param[in] LBA The starting logical block address to read from on - the device. - @param[in, out] Token A pointer to the token associated with the transaction. - @param[in] BufferSize The size of the Buffer in bytes. This must be a multiple - of the intrinsic block size of the device. - @param[out] Buffer A pointer to the destination buffer for the data. The - caller is responsible for either having implicit or - explicit ownership of the buffer. - @param[in] Index A pointer to the configuration table index. This is - optional. - @param[in] CryptoIvInput A pointer to a buffer that contains additional - cryptographic parameters as required by the capability - referenced by the configuration table index, such as - cryptographic initialization vector. - - @retval EFI_SUCCESS The read request was queued if Token-> Event is not NULL. - The data was read correctly from the device if the - Token->Event is NULL. - @retval EFI_DEVICE_ERROR The device reported an error while attempting to perform - the read operation and/or decryption operation. - @retval EFI_NO_MEDIA There is no media in the device. - @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. - @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic - block size of the device. - @retval EFI_INVALID_PARAMETER This is NULL, or the read request contains LBAs that are - not valid, or the buffer is not on proper alignment. - @retval EFI_INVALID_PARAMETER CryptoIvInput is incorrect. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of - resources. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_READ_EXTENDED) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - IN UINT32 MediaId, - IN EFI_LBA LBA, - IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN *Token, - IN UINT64 BufferSize, - OUT VOID *Buffer, - IN UINT64 *Index OPTIONAL, - IN VOID *CryptoIvInput OPTIONAL - ); - -/** - Optionally encrypts a specified number of blocks inline and then writes to the - device. - - The WriteExtended() function allows the caller to perform a storage device write - operation. The function encrypts the requested number of blocks inline if Index - is specified and then writes them to the device. All the blocks are encrypted - (if encryption requested) and written, or an error is returned. - - If there is no media in the device, the function returns EFI_NO_MEDIA. If the - MediaId is not the ID for the current media in the device, the function returns - EFI_MEDIA_CHANGED. - - If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking - I/O is being used, the Event associated with this request will not be signaled. - - In addition to standard storage transaction parameters (LBA, IO size, and buffer), - this command will also specify a configuration table Index and a CryptoIvInput - when data has to be decrypted inline by the controller before being written to - the storage device. If no Index parameter is specified, no encryption is performed. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[in] MediaId The media ID that the read request is for. - @param[in] LBA The starting logical block address to read from on - the device. - @param[in, out] Token A pointer to the token associated with the transaction. - @param[in] BufferSize The size of the Buffer in bytes. This must be a multiple - of the intrinsic block size of the device. - @param[in] Buffer A pointer to the source buffer for the data. - @param[in] Index A pointer to the configuration table index. This is - optional. - @param[in] CryptoIvInput A pointer to a buffer that contains additional - cryptographic parameters as required by the capability - referenced by the configuration table index, such as - cryptographic initialization vector. - - @retval EFI_SUCCESS The request to encrypt (optionally) and write was queued - if Event is not NULL. The data was encrypted (optionally) - and written correctly to the device if the Event is NULL. - @retval EFI_WRITE_PROTECTED The device cannot be written to. - @retval EFI_NO_MEDIA There is no media in the device. - @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. - @retval EFI_DEVICE_ERROR The device reported an error while attempting to encrypt - blocks or to perform the write operation. - @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic - block size of the device. - @retval EFI_INVALID_PARAMETER This is NULL, or the write request contains LBAs that are - not valid, or the buffer is not on proper alignment. - @retval EFI_INVALID_PARAMETER CryptoIvInput is incorrect. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of - resources. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_WRITE_EXTENDED) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - IN UINT32 MediaId, - IN EFI_LBA LBA, - IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN *Token, - IN UINT64 BufferSize, - IN VOID *Buffer, - IN UINT64 *Index OPTIONAL, - IN VOID *CryptoIvInput OPTIONAL - ); - -/** - Flushes all modified data toa physical block device. - - The FlushBlocks() function flushes all modified data to the physical block device. - Any modified data that has to be encrypted must have been already encrypted as a - part of WriteExtended() operation - inline crypto operation cannot be a part of - flush operation. - - All data written to the device prior to the flush must be physically written before - returning EFI_SUCCESS from this function. This would include any cached data the - driver may have cached, and cached data the device may have cached. A flush may - cause a read request following the flush to force a device access. - - If EFI_DEVICE_ERROR, EFI_NO_MEDIA, EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is - returned and non-blocking I/O is being used, the Event associated with this request - will not be signaled. - - @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. - @param[in, out] Token A pointer to the token associated with the transaction. - - @retval EFI_SUCCESS The flush request was queued if Event is not NULL. All - outstanding data was written correctly to the device if - the Event is NULL. - @retval EFI_DEVICE_ERROR The device reported an error while attempting to write data. - @retval EFI_WRITE_PROTECTED The device cannot be written to. - @retval EFI_NO_MEDIA There is no media in the device. - @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of - resources. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_BLOCK_IO_CRYPTO_FLUSH) ( - IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, - IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN *Token - ); - -typedef struct { - // - // GUID of the algorithm. - // - EFI_GUID Algorithm; - // - // Specifies KeySizein bits used with this Algorithm. - // - UINT64 KeySize; - // - // Specifies bitmask of block sizes supported by this algorithm. - // Bit j being set means that 2^j bytes crypto block size is supported. - // - UINT64 CryptoBlockSizeBitMask; -} EFI_BLOCK_IO_CRYPTO_CAPABILITY; - -/// -/// EFI_BLOCK_IO_CRYPTO_IV_INPUT structure is used as a common header in CryptoIvInput -/// parameters passed to the ReadExtended and WriteExtended methods for Inline -/// Cryptographic Interface. -/// Its purpose is to pass size of the entire CryptoIvInputparameter memory buffer to -/// the Inline Cryptographic Interface. -/// -typedef struct { - UINT64 InputSize; -} EFI_BLOCK_IO_CRYPTO_IV_INPUT; - -#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_XTS \ - { \ - 0x2f87ba6a, 0x5c04, 0x4385, {0xa7, 0x80, 0xf3, 0xbf, 0x78, 0xa9, 0x7b, 0xec} \ - } - -extern EFI_GUID gEfiBlockIoCryptoAlgoAesXtsGuid; - -typedef struct { - EFI_BLOCK_IO_CRYPTO_IV_INPUT Header; - UINT64 CryptoBlockNumber; - UINT64 CryptoBlockByteSize; -} EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_XTS; - -#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_CBC_MICROSOFT_BITLOCKER \ - { \ - 0x689e4c62, 0x70bf, 0x4cf3, {0x88, 0xbb, 0x33, 0xb3, 0x18, 0x26, 0x86, 0x70} \ - } - -extern EFI_GUID gEfiBlockIoCryptoAlgoAesCbcMsBitlockerGuid; - -typedef struct { - EFI_BLOCK_IO_CRYPTO_IV_INPUT Header; - UINT64 CryptoBlockByteOffset; - UINT64 CryptoBlockByteSize; -} EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_CBC_MICROSOFT_BITLOCKER; - -#define EFI_BLOCK_IO_CRYPTO_INDEX_ANY 0xFFFFFFFFFFFFFFFF - -typedef struct { - // - // Is inline cryptographic capability supported on this device. - // - BOOLEAN Supported; - // - // Maximum number of keys that can be configured at the same time. - // - UINT64 KeyCount; - // - // Number of supported capabilities. - // - UINT64 CapabilityCount; - // - // Array of supported capabilities. - // - EFI_BLOCK_IO_CRYPTO_CAPABILITY Capabilities[1]; -} EFI_BLOCK_IO_CRYPTO_CAPABILITIES; - -typedef struct { - // - // Configuration table index. A special Index EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be - // used to set any available entry in the configuration table. - // - UINT64 Index; - // - // Identifies the owner of the configuration table entry. Entry can also be used - // with the Nil value to clear key from the configuration table index. - // - EFI_GUID KeyOwnerGuid; - // - // A supported capability to be used. The CryptoBlockSizeBitMask field of the - // structure should have only one bit set from the supported mask. - // - EFI_BLOCK_IO_CRYPTO_CAPABILITY Capability; - // - // Pointer to the key. The size of the key is defined by the KeySize field of - // the capability specified by the Capability parameter. - // - VOID *CryptoKey; -} EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY; - -typedef struct { - // - // Configuration table index. - // - UINT64 Index; - // - // Identifies the current owner of the entry. - // - EFI_GUID KeyOwnerGuid; - // - // The capability to be used. The CryptoBlockSizeBitMask field of the structure - // has only one bit set from the supported mask. - // - EFI_BLOCK_IO_CRYPTO_CAPABILITY Capability; -} EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY; - - -/// -/// The EFI_BLOCK_IO_CRYPTO_PROTOCOL defines a UEFI protocol that can be used by UEFI -/// drivers and applications to perform block encryption on a storage device, such as UFS. -/// -struct _EFI_BLOCK_IO_CRYPTO_PROTOCOL { - EFI_BLOCK_IO_MEDIA *Media; - EFI_BLOCK_IO_CRYPTO_RESET Reset; - EFI_BLOCK_IO_CRYPTO_GET_CAPABILITIES GetCapabilities; - EFI_BLOCK_IO_CRYPTO_SET_CONFIGURATION SetConfiguration; - EFI_BLOCK_IO_CRYPTO_GET_CONFIGURATION GetConfiguration; - EFI_BLOCK_IO_CRYPTO_READ_EXTENDED ReadExtended; - EFI_BLOCK_IO_CRYPTO_WRITE_EXTENDED WriteExtended; - EFI_BLOCK_IO_CRYPTO_FLUSH FlushBlocks; -}; - -extern EFI_GUID gEfiBlockIoCryptoProtocolGuid; - -#endif - +/** @file + The UEFI Inline Cryptographic Interface protocol provides services to abstract + access to inline cryptographic capabilities. + + Copyright (c) 2015, Intel Corporation. All rights reserved.
+ This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef __BLOCK_IO_CRYPTO_H__ +#define __BLOCK_IO_CRYPTO_H__ + +#include + +#define EFI_BLOCK_IO_CRYPTO_PROTOCOL_GUID \ + { \ + 0xa00490ba, 0x3f1a, 0x4b4c, {0xab, 0x90, 0x4f, 0xa9, 0x97, 0x26, 0xa1, 0xe8} \ + } + +typedef struct _EFI_BLOCK_IO_CRYPTO_PROTOCOL EFI_BLOCK_IO_CRYPTO_PROTOCOL; + +/// +/// The struct of Block I/O Crypto Token. +/// +typedef struct { + // + // If Event is NULL, then blocking I/O is performed. If Event is not NULL and + // non-blocking I/O is supported, then non-blocking I/O is performed, and + // Event will be signaled when the read request is completed and data was + // decrypted (when Index was specified). + // + EFI_EVENT Event; + // + // Defines whether or not the signaled event encountered an error. + // + EFI_STATUS TransactionStatus; +} EFI_BLOCK_IO_CRYPTO_TOKEN; + + +/** + Reset the block device hardware. + + The Reset() function resets the block device hardware. + + As part of the initialization process, the firmware/device will make a quick but + reasonable attempt to verify that the device is functioning. + + If the ExtendedVerificationflag is TRUE the firmware may take an extended amount + of time to verify the device is operating on reset. Otherwise the reset operation + is to occur as quickly as possible. + + The hardware verification process is not defined by this specification and is left + up to the platform firmware or driver to implement. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[in] ExtendedVerification Indicates that the driver may perform a more exhausive + verfication operation of the device during reset. + + @retval EFI_SUCCESS The block device was reset. + @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could + not be reset. + @retval EFI_INVALID_PARAMETER This is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_RESET) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + IN BOOLEAN ExtendedVerification + ); + +/** + Get the capabilities of the underlying inline cryptographic interface. + + The GetCapabilities() function determines whether pre-OS controllable inline crypto + is supported by the system for the current disk and, if so, returns the capabilities + of the crypto engine. + + The caller is responsible for providing the Capabilities structure with a sufficient + number of entries. + + If the structure is too small, the EFI_BUFFER_TOO_SMALL error code is returned and the + CapabilityCount field contains the number of entries needed to contain the capabilities. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[out] Capabilities Pointer to the EFI_BLOCK_IO_CRYPTO_CAPABILITIES structure. + + @retval EFI_SUCCESS The ICI is ready for use. + @retval EFI_BUFFER_TOO_SMALL The Capabilities structure was too small. The number of + entries needed is returned in the CapabilityCount field + of the structure. + @retval EFI_NO_RESPONSE No response was received from the ICI. + @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER Capabilities is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_GET_CAPABILITIES) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + OUT EFI_BLOCK_IO_CRYPTO_CAPABILITIES *Capabilities + ); + +/** + Set the configuration of the underlying inline cryptographic interface. + + The SetConfiguration() function allows the user to set the current configuration of the + inline cryptographic interface and should be called before attempting any crypto operations. + + This configures the configuration table entries with algorithms, key sizes and keys. Each + configured entry can later be referred to by index at the time of storage transaction. + + The configuration table index will refer to the combination ofKeyOwnerGuid, Algorithm, and + CryptoKey. + + KeyOwnerGuid identifies the component taking ownership of the entry. It helps components to + identify their own entries, cooperate with other owner components, and avoid conflicts. This + Guid identifier is there to help coordination between cooperating components and not a security + or synchronization feature. The Nil GUID can be used by a component to release use of entry + owned. It is also used to identify potentially available entries (see GetConfiguration). + + CryptoKey specifies algorithm-specific key material to use within parameters of selected crypto + capability. + + This function is called infrequently typically once, on device start, before IO starts. It + can be called at later times in cases the number of keysused on the drive is higher than what + can be configured at a time or a new key has to be added. + + Components setting or changing an entry or entries for a given index or indices must ensure + that IO referencing affected indices is temporarily blocked (run-down) at the time of change. + + Indices parameters in each parameter table entry allow to set only a portion of the available + table entries in the crypto module anywhere from single entry to entire table supported. + + If corresponding table entry or entries being set are already in use by another owner the call + should be failed and none of the entries should be modified. The interface implementation must + enforce atomicity of this operation (should either succeed fully or fail completely without + modifying state). + + Note that components using GetConfiguration command to discover available entries should be + prepared that by the time of calling SetConfiguration the previously available entry may have + become occupied. Such components should be prepared to re-try the sequence of operations. + + Alternatively EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be used to have the implementation discover + and allocate available,if any, indices atomically. + + An optional ResultingTable pointer can be provided by the caller to receive the newly configured + entries. The array provided by the caller must have at least ConfigurationCount of entries. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[in] ConfigurationCount Number of entries being configured with this call. + @param[in] ConfigurationTable Pointer to a table used to populate the configuration table. + @param[out] ResultingTable Optional pointer to a table that receives the newly configured + entries. + + @retval EFI_SUCCESS The ICI is ready for use. + @retval EFI_NO_RESPONSE No response was received from the ICI. + @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER ConfigurationTable is NULL. + @retval EFI_INVALID_PARAMETER ConfigurationCount is 0. + @retval EFI_OUT_OF_RESOURCES Could not find the requested number of available entries in the + configuration table. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_SET_CONFIGURATION) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + IN UINT64 ConfigurationCount, + IN EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY *ConfigurationTable, + OUT EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY *ResultingTable OPTIONAL + ); + + +/** + Get the configuration of the underlying inline cryptographic interface. + + The GetConfiguration() function allows the user to get the configuration of the inline + cryptographic interface. + + Retrieves, entirely or partially, the currently configured key table. Note that the keys + themselves are not retrieved, but rather just indices, owner GUIDs and capabilities. + + If fewer entries than specified by ConfigurationCount are returned, the Index field of the + unused entries is set to EFI_BLOCK_IO_CRYPTO_INDEX_ANY. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[in] StartIndex Configuration table index at which to start the configuration + query. + @param[in] ConfigurationCount Number of entries to return in the response table. + @param[in] KeyOwnerGuid Optional parameter to filter response down to entries with a + given owner. A pointer to the Nil value can be used to return + available entries. Set to NULL when no owner filtering is required. + @param[out] ConfigurationTable Table of configured configuration table entries (with no CryptoKey + returned): configuration table index, KeyOwnerGuid, Capability. + Should have sufficient space to store up to ConfigurationCount + entries. + + @retval EFI_SUCCESS The ICI is ready for use. + @retval EFI_NO_RESPONSE No response was received from the ICI. + @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER Configuration table is NULL. + @retval EFI_INVALID_PARAMETER StartIndex is out of bounds. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_GET_CONFIGURATION) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + IN UINT64 StartIndex, + IN UINT64 ConfigurationCount, + IN EFI_GUID *KeyOwnerGuid OPTIONAL, + OUT EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY *ConfigurationTable +); + +/** + Reads the requested number of blocks from the device and optionally decrypts + them inline. + + TheReadExtended() function allows the caller to perform a storage device read + operation. The function reads the requested number of blocks from the device + and then if Index is specified decrypts them inline. All the blocks are read + and decrypted (if decryption requested), or an error is returned. + + If there is no media in the device, the function returns EFI_NO_MEDIA. If the + MediaId is not the ID for the current media in the device, the function returns + EFI_MEDIA_CHANGED. + + If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking + I/O is being used, the Event associated with this request will not be signaled. + + In addition to standard storage transaction parameters (LBA, IO size, and buffer), + this command will also specify a configuration table Index and CryptoIvInput + when data has to be decrypted inline by the controller after being read from + the storage device. If an Index parameter is not specified, no decryption is + performed. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[in] MediaId The media ID that the read request is for. + @param[in] LBA The starting logical block address to read from on + the device. + @param[in, out] Token A pointer to the token associated with the transaction. + @param[in] BufferSize The size of the Buffer in bytes. This must be a multiple + of the intrinsic block size of the device. + @param[out] Buffer A pointer to the destination buffer for the data. The + caller is responsible for either having implicit or + explicit ownership of the buffer. + @param[in] Index A pointer to the configuration table index. This is + optional. + @param[in] CryptoIvInput A pointer to a buffer that contains additional + cryptographic parameters as required by the capability + referenced by the configuration table index, such as + cryptographic initialization vector. + + @retval EFI_SUCCESS The read request was queued if Token-> Event is not NULL. + The data was read correctly from the device if the + Token->Event is NULL. + @retval EFI_DEVICE_ERROR The device reported an error while attempting to perform + the read operation and/or decryption operation. + @retval EFI_NO_MEDIA There is no media in the device. + @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. + @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic + block size of the device. + @retval EFI_INVALID_PARAMETER This is NULL, or the read request contains LBAs that are + not valid, or the buffer is not on proper alignment. + @retval EFI_INVALID_PARAMETER CryptoIvInput is incorrect. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of + resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_READ_EXTENDED) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + IN UINT32 MediaId, + IN EFI_LBA LBA, + IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN *Token, + IN UINT64 BufferSize, + OUT VOID *Buffer, + IN UINT64 *Index OPTIONAL, + IN VOID *CryptoIvInput OPTIONAL + ); + +/** + Optionally encrypts a specified number of blocks inline and then writes to the + device. + + The WriteExtended() function allows the caller to perform a storage device write + operation. The function encrypts the requested number of blocks inline if Index + is specified and then writes them to the device. All the blocks are encrypted + (if encryption requested) and written, or an error is returned. + + If there is no media in the device, the function returns EFI_NO_MEDIA. If the + MediaId is not the ID for the current media in the device, the function returns + EFI_MEDIA_CHANGED. + + If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking + I/O is being used, the Event associated with this request will not be signaled. + + In addition to standard storage transaction parameters (LBA, IO size, and buffer), + this command will also specify a configuration table Index and a CryptoIvInput + when data has to be decrypted inline by the controller before being written to + the storage device. If no Index parameter is specified, no encryption is performed. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[in] MediaId The media ID that the read request is for. + @param[in] LBA The starting logical block address to read from on + the device. + @param[in, out] Token A pointer to the token associated with the transaction. + @param[in] BufferSize The size of the Buffer in bytes. This must be a multiple + of the intrinsic block size of the device. + @param[in] Buffer A pointer to the source buffer for the data. + @param[in] Index A pointer to the configuration table index. This is + optional. + @param[in] CryptoIvInput A pointer to a buffer that contains additional + cryptographic parameters as required by the capability + referenced by the configuration table index, such as + cryptographic initialization vector. + + @retval EFI_SUCCESS The request to encrypt (optionally) and write was queued + if Event is not NULL. The data was encrypted (optionally) + and written correctly to the device if the Event is NULL. + @retval EFI_WRITE_PROTECTED The device cannot be written to. + @retval EFI_NO_MEDIA There is no media in the device. + @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. + @retval EFI_DEVICE_ERROR The device reported an error while attempting to encrypt + blocks or to perform the write operation. + @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic + block size of the device. + @retval EFI_INVALID_PARAMETER This is NULL, or the write request contains LBAs that are + not valid, or the buffer is not on proper alignment. + @retval EFI_INVALID_PARAMETER CryptoIvInput is incorrect. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of + resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_WRITE_EXTENDED) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + IN UINT32 MediaId, + IN EFI_LBA LBA, + IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN *Token, + IN UINT64 BufferSize, + IN VOID *Buffer, + IN UINT64 *Index OPTIONAL, + IN VOID *CryptoIvInput OPTIONAL + ); + +/** + Flushes all modified data toa physical block device. + + The FlushBlocks() function flushes all modified data to the physical block device. + Any modified data that has to be encrypted must have been already encrypted as a + part of WriteExtended() operation - inline crypto operation cannot be a part of + flush operation. + + All data written to the device prior to the flush must be physically written before + returning EFI_SUCCESS from this function. This would include any cached data the + driver may have cached, and cached data the device may have cached. A flush may + cause a read request following the flush to force a device access. + + If EFI_DEVICE_ERROR, EFI_NO_MEDIA, EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is + returned and non-blocking I/O is being used, the Event associated with this request + will not be signaled. + + @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance. + @param[in, out] Token A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS The flush request was queued if Event is not NULL. All + outstanding data was written correctly to the device if + the Event is NULL. + @retval EFI_DEVICE_ERROR The device reported an error while attempting to write data. + @retval EFI_WRITE_PROTECTED The device cannot be written to. + @retval EFI_NO_MEDIA There is no media in the device. + @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of + resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_BLOCK_IO_CRYPTO_FLUSH) ( + IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This, + IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN *Token + ); + +typedef struct { + // + // GUID of the algorithm. + // + EFI_GUID Algorithm; + // + // Specifies KeySizein bits used with this Algorithm. + // + UINT64 KeySize; + // + // Specifies bitmask of block sizes supported by this algorithm. + // Bit j being set means that 2^j bytes crypto block size is supported. + // + UINT64 CryptoBlockSizeBitMask; +} EFI_BLOCK_IO_CRYPTO_CAPABILITY; + +/// +/// EFI_BLOCK_IO_CRYPTO_IV_INPUT structure is used as a common header in CryptoIvInput +/// parameters passed to the ReadExtended and WriteExtended methods for Inline +/// Cryptographic Interface. +/// Its purpose is to pass size of the entire CryptoIvInputparameter memory buffer to +/// the Inline Cryptographic Interface. +/// +typedef struct { + UINT64 InputSize; +} EFI_BLOCK_IO_CRYPTO_IV_INPUT; + +#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_XTS \ + { \ + 0x2f87ba6a, 0x5c04, 0x4385, {0xa7, 0x80, 0xf3, 0xbf, 0x78, 0xa9, 0x7b, 0xec} \ + } + +extern EFI_GUID gEfiBlockIoCryptoAlgoAesXtsGuid; + +typedef struct { + EFI_BLOCK_IO_CRYPTO_IV_INPUT Header; + UINT64 CryptoBlockNumber; + UINT64 CryptoBlockByteSize; +} EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_XTS; + +#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_CBC_MICROSOFT_BITLOCKER \ + { \ + 0x689e4c62, 0x70bf, 0x4cf3, {0x88, 0xbb, 0x33, 0xb3, 0x18, 0x26, 0x86, 0x70} \ + } + +extern EFI_GUID gEfiBlockIoCryptoAlgoAesCbcMsBitlockerGuid; + +typedef struct { + EFI_BLOCK_IO_CRYPTO_IV_INPUT Header; + UINT64 CryptoBlockByteOffset; + UINT64 CryptoBlockByteSize; +} EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_CBC_MICROSOFT_BITLOCKER; + +#define EFI_BLOCK_IO_CRYPTO_INDEX_ANY 0xFFFFFFFFFFFFFFFF + +typedef struct { + // + // Is inline cryptographic capability supported on this device. + // + BOOLEAN Supported; + // + // Maximum number of keys that can be configured at the same time. + // + UINT64 KeyCount; + // + // Number of supported capabilities. + // + UINT64 CapabilityCount; + // + // Array of supported capabilities. + // + EFI_BLOCK_IO_CRYPTO_CAPABILITY Capabilities[1]; +} EFI_BLOCK_IO_CRYPTO_CAPABILITIES; + +typedef struct { + // + // Configuration table index. A special Index EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be + // used to set any available entry in the configuration table. + // + UINT64 Index; + // + // Identifies the owner of the configuration table entry. Entry can also be used + // with the Nil value to clear key from the configuration table index. + // + EFI_GUID KeyOwnerGuid; + // + // A supported capability to be used. The CryptoBlockSizeBitMask field of the + // structure should have only one bit set from the supported mask. + // + EFI_BLOCK_IO_CRYPTO_CAPABILITY Capability; + // + // Pointer to the key. The size of the key is defined by the KeySize field of + // the capability specified by the Capability parameter. + // + VOID *CryptoKey; +} EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY; + +typedef struct { + // + // Configuration table index. + // + UINT64 Index; + // + // Identifies the current owner of the entry. + // + EFI_GUID KeyOwnerGuid; + // + // The capability to be used. The CryptoBlockSizeBitMask field of the structure + // has only one bit set from the supported mask. + // + EFI_BLOCK_IO_CRYPTO_CAPABILITY Capability; +} EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY; + + +/// +/// The EFI_BLOCK_IO_CRYPTO_PROTOCOL defines a UEFI protocol that can be used by UEFI +/// drivers and applications to perform block encryption on a storage device, such as UFS. +/// +struct _EFI_BLOCK_IO_CRYPTO_PROTOCOL { + EFI_BLOCK_IO_MEDIA *Media; + EFI_BLOCK_IO_CRYPTO_RESET Reset; + EFI_BLOCK_IO_CRYPTO_GET_CAPABILITIES GetCapabilities; + EFI_BLOCK_IO_CRYPTO_SET_CONFIGURATION SetConfiguration; + EFI_BLOCK_IO_CRYPTO_GET_CONFIGURATION GetConfiguration; + EFI_BLOCK_IO_CRYPTO_READ_EXTENDED ReadExtended; + EFI_BLOCK_IO_CRYPTO_WRITE_EXTENDED WriteExtended; + EFI_BLOCK_IO_CRYPTO_FLUSH FlushBlocks; +}; + +extern EFI_GUID gEfiBlockIoCryptoProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/NvmExpressPassthru.h b/MdePkg/Include/Protocol/NvmExpressPassthru.h index 20e40b0ca0..ebd7a8b78a 100644 --- a/MdePkg/Include/Protocol/NvmExpressPassthru.h +++ b/MdePkg/Include/Protocol/NvmExpressPassthru.h @@ -1,286 +1,286 @@ -/** @file - This protocol provides services that allow NVM Express commands to be sent to an - NVM Express controller or to a specific namespace in a NVM Express controller. - This protocol interface is optimized for storage. - - Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.
- This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php. - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef _UEFI_NVM_EXPRESS_PASS_THRU_H_ -#define _UEFI_NVM_EXPRESS_PASS_THRU_H_ - -#define EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL_GUID \ - { \ - 0x52c78312, 0x8edc, 0x4233, { 0x98, 0xf2, 0x1a, 0x1a, 0xa5, 0xe3, 0x88, 0xa5 } \ - } - -typedef struct _EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL; - -typedef struct { - UINT32 Attributes; - UINT32 IoAlign; - UINT32 NvmeVersion; -} EFI_NVM_EXPRESS_PASS_THRU_MODE; - -// -// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface is -// for directly addressable namespaces. -// -#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_PHYSICAL 0x0001 -// -// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface is -// for a single volume logical namespace comprised of multiple namespaces. -// -#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_LOGICAL 0x0002 -// -// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface -// supports non-blocking I/O. -// -#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_NONBLOCKIO 0x0004 -// -// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface -// supports NVM command set. -// -#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_CMD_SET_NVM 0x0008 - -// -// FusedOperation -// -#define NORMAL_CMD 0x00 -#define FUSED_FIRST_CMD 0x01 -#define FUSED_SECOND_CMD 0x02 - -typedef struct { - UINT32 Opcode:8; - UINT32 FusedOperation:2; - UINT32 Reserved:22; -} NVME_CDW0; - -// -// Flags -// -#define CDW2_VALID 0x01 -#define CDW3_VALID 0x02 -#define CDW10_VALID 0x04 -#define CDW11_VALID 0x08 -#define CDW12_VALID 0x10 -#define CDW13_VALID 0x20 -#define CDW14_VALID 0x40 -#define CDW15_VALID 0x80 - -// -// Queue Type -// -#define NVME_ADMIN_QUEUE 0x00 -#define NVME_IO_QUEUE 0x01 - -typedef struct { - NVME_CDW0 Cdw0; - UINT8 Flags; - UINT32 Nsid; - UINT32 Cdw2; - UINT32 Cdw3; - UINT32 Cdw10; - UINT32 Cdw11; - UINT32 Cdw12; - UINT32 Cdw13; - UINT32 Cdw14; - UINT32 Cdw15; -} EFI_NVM_EXPRESS_COMMAND; - -typedef struct { - UINT32 DW0; - UINT32 DW1; - UINT32 DW2; - UINT32 DW3; -} EFI_NVM_EXPRESS_COMPLETION; - -typedef struct { - UINT64 CommandTimeout; - VOID *TransferBuffer; - UINT32 TransferLength; - VOID *MetadataBuffer; - UINT32 MetadataLength; - UINT8 QueueType; - EFI_NVM_EXPRESS_COMMAND *NvmeCmd; - EFI_NVM_EXPRESS_COMPLETION *NvmeCompletion; -} EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET; - -// -// Protocol funtion prototypes -// -/** - Sends an NVM Express Command Packet to an NVM Express controller or namespace. This function supports - both blocking I/O and non-blocking I/O. The blocking I/O functionality is required, and the non-blocking - I/O functionality is optional. - - - @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. - @param[in] NamespaceId A 32 bit namespace ID as defined in the NVMe specification to which the NVM Express Command - Packet will be sent. A value of 0 denotes the NVM Express controller, a value of all 0xFF's - (all bytes are 0xFF) in the namespace ID specifies that the command packet should be sent to - all valid namespaces. - @param[in,out] Packet A pointer to the NVM Express Command Packet. - @param[in] Event If non-blocking I/O is not supported then Event is ignored, and blocking I/O is performed. - If Event is NULL, then blocking I/O is performed. If Event is not NULL and non-blocking I/O - is supported, then non-blocking I/O is performed, and Event will be signaled when the NVM - Express Command Packet completes. - - @retval EFI_SUCCESS The NVM Express Command Packet was sent by the host. TransferLength bytes were transferred - to, or from DataBuffer. - @retval EFI_BAD_BUFFER_SIZE The NVM Express Command Packet was not executed. The number of bytes that could be transferred - is returned in TransferLength. - @retval EFI_NOT_READY The NVM Express Command Packet could not be sent because the controller is not ready. The caller - may retry again later. - @retval EFI_DEVICE_ERROR A device error occurred while attempting to send the NVM Express Command Packet. - @retval EFI_INVALID_PARAMETER NamespaceId or the contents of EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET are invalid. The NVM - Express Command Packet was not sent, so no additional status information is available. - @retval EFI_UNSUPPORTED The command described by the NVM Express Command Packet is not supported by the NVM Express - controller. The NVM Express Command Packet was not sent so no additional status information - is available. - @retval EFI_TIMEOUT A timeout occurred while waiting for the NVM Express Command Packet to execute. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_PASSTHRU)( - IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, - IN UINT32 NamespaceId, - IN OUT EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET *Packet, - IN EFI_EVENT Event OPTIONAL - ); - -/** - Used to retrieve the next namespace ID for this NVM Express controller. - - The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNextNamespace() function retrieves the next valid - namespace ID on this NVM Express controller. - - If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the first valid namespace - ID defined on the NVM Express controller is returned in the location pointed to by NamespaceId - and a status of EFI_SUCCESS is returned. - - If on input the value pointed to by NamespaceId is an invalid namespace ID other than 0xFFFFFFFF, - then EFI_INVALID_PARAMETER is returned. - - If on input the value pointed to by NamespaceId is a valid namespace ID, then the next valid - namespace ID on the NVM Express controller is returned in the location pointed to by NamespaceId, - and EFI_SUCCESS is returned. - - If the value pointed to by NamespaceId is the namespace ID of the last namespace on the NVM - Express controller, then EFI_NOT_FOUND is returned. - - @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. - @param[in,out] NamespaceId On input, a pointer to a legal NamespaceId for an NVM Express - namespace present on the NVM Express controller. On output, a - pointer to the next NamespaceId of an NVM Express namespace on - an NVM Express controller. An input value of 0xFFFFFFFF retrieves - the first NamespaceId for an NVM Express namespace present on an - NVM Express controller. - - @retval EFI_SUCCESS The Namespace ID of the next Namespace was returned. - @retval EFI_NOT_FOUND There are no more namespaces defined on this controller. - @retval EFI_INVALID_PARAMETER NamespaceId is an invalid value other than 0xFFFFFFFF. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_GET_NEXT_NAMESPACE)( - IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, - IN OUT UINT32 *NamespaceId - ); - -/** - Used to allocate and build a device path node for an NVM Express namespace on an NVM Express controller. - - The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.BuildDevicePath() function allocates and builds a single device - path node for the NVM Express namespace specified by NamespaceId. - - If the NamespaceId is not valid, then EFI_NOT_FOUND is returned. - - If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. - - If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES is returned. - - Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of DevicePath are - initialized to describe the NVM Express namespace specified by NamespaceId, and EFI_SUCCESS is returned. - - @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. - @param[in] NamespaceId The NVM Express namespace ID for which a device path node is to be - allocated and built. Caller must set the NamespaceId to zero if the - device path node will contain a valid UUID. - @param[in,out] DevicePath A pointer to a single device path node that describes the NVM Express - namespace specified by NamespaceId. This function is responsible for - allocating the buffer DevicePath with the boot service AllocatePool(). - It is the caller's responsibility to free DevicePath when the caller - is finished with DevicePath. - @retval EFI_SUCCESS The device path node that describes the NVM Express namespace specified - by NamespaceId was allocated and returned in DevicePath. - @retval EFI_NOT_FOUND The NamespaceId is not valid. - @retval EFI_INVALID_PARAMETER DevicePath is NULL. - @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the DevicePath node. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH)( - IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, - IN UINT32 NamespaceId, - IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath - ); - -/** - Used to translate a device path node to a namespace ID. - - The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNamespace() function determines the namespace ID associated with the - namespace described by DevicePath. - - If DevicePath is a device path node type that the NVM Express Pass Thru driver supports, then the NVM Express - Pass Thru driver will attempt to translate the contents DevicePath into a namespace ID. - - If this translation is successful, then that namespace ID is returned in NamespaceId, and EFI_SUCCESS is returned - - @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. - @param[in] DevicePath A pointer to the device path node that describes an NVM Express namespace on - the NVM Express controller. - @param[out] NamespaceId The NVM Express namespace ID contained in the device path node. - - @retval EFI_SUCCESS DevicePath was successfully translated to NamespaceId. - @retval EFI_INVALID_PARAMETER If DevicePath or NamespaceId are NULL, then EFI_INVALID_PARAMETER is returned. - @retval EFI_UNSUPPORTED If DevicePath is not a device path node type that the NVM Express Pass Thru driver - supports, then EFI_UNSUPPORTED is returned. - @retval EFI_NOT_FOUND If DevicePath is a device path node type that the NVM Express Pass Thru driver - supports, but there is not a valid translation from DevicePath to a namespace ID, - then EFI_NOT_FOUND is returned. -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_GET_NAMESPACE)( - IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, - IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, - OUT UINT32 *NamespaceId - ); - -// -// Protocol Interface Structure -// -struct _EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL { - EFI_NVM_EXPRESS_PASS_THRU_MODE *Mode; - EFI_NVM_EXPRESS_PASS_THRU_PASSTHRU PassThru; - EFI_NVM_EXPRESS_PASS_THRU_GET_NEXT_NAMESPACE GetNextNamespace; - EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath; - EFI_NVM_EXPRESS_PASS_THRU_GET_NAMESPACE GetNamespace; -}; - -extern EFI_GUID gEfiNvmExpressPassThruProtocolGuid; - -#endif - +/** @file + This protocol provides services that allow NVM Express commands to be sent to an + NVM Express controller or to a specific namespace in a NVM Express controller. + This protocol interface is optimized for storage. + + Copyright (c) 2013 - 2015, Intel Corporation. All rights reserved.
+ This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php. + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef _UEFI_NVM_EXPRESS_PASS_THRU_H_ +#define _UEFI_NVM_EXPRESS_PASS_THRU_H_ + +#define EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL_GUID \ + { \ + 0x52c78312, 0x8edc, 0x4233, { 0x98, 0xf2, 0x1a, 0x1a, 0xa5, 0xe3, 0x88, 0xa5 } \ + } + +typedef struct _EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL; + +typedef struct { + UINT32 Attributes; + UINT32 IoAlign; + UINT32 NvmeVersion; +} EFI_NVM_EXPRESS_PASS_THRU_MODE; + +// +// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface is +// for directly addressable namespaces. +// +#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_PHYSICAL 0x0001 +// +// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface is +// for a single volume logical namespace comprised of multiple namespaces. +// +#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_LOGICAL 0x0002 +// +// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface +// supports non-blocking I/O. +// +#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_NONBLOCKIO 0x0004 +// +// If this bit is set, then the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL interface +// supports NVM command set. +// +#define EFI_NVM_EXPRESS_PASS_THRU_ATTRIBUTES_CMD_SET_NVM 0x0008 + +// +// FusedOperation +// +#define NORMAL_CMD 0x00 +#define FUSED_FIRST_CMD 0x01 +#define FUSED_SECOND_CMD 0x02 + +typedef struct { + UINT32 Opcode:8; + UINT32 FusedOperation:2; + UINT32 Reserved:22; +} NVME_CDW0; + +// +// Flags +// +#define CDW2_VALID 0x01 +#define CDW3_VALID 0x02 +#define CDW10_VALID 0x04 +#define CDW11_VALID 0x08 +#define CDW12_VALID 0x10 +#define CDW13_VALID 0x20 +#define CDW14_VALID 0x40 +#define CDW15_VALID 0x80 + +// +// Queue Type +// +#define NVME_ADMIN_QUEUE 0x00 +#define NVME_IO_QUEUE 0x01 + +typedef struct { + NVME_CDW0 Cdw0; + UINT8 Flags; + UINT32 Nsid; + UINT32 Cdw2; + UINT32 Cdw3; + UINT32 Cdw10; + UINT32 Cdw11; + UINT32 Cdw12; + UINT32 Cdw13; + UINT32 Cdw14; + UINT32 Cdw15; +} EFI_NVM_EXPRESS_COMMAND; + +typedef struct { + UINT32 DW0; + UINT32 DW1; + UINT32 DW2; + UINT32 DW3; +} EFI_NVM_EXPRESS_COMPLETION; + +typedef struct { + UINT64 CommandTimeout; + VOID *TransferBuffer; + UINT32 TransferLength; + VOID *MetadataBuffer; + UINT32 MetadataLength; + UINT8 QueueType; + EFI_NVM_EXPRESS_COMMAND *NvmeCmd; + EFI_NVM_EXPRESS_COMPLETION *NvmeCompletion; +} EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET; + +// +// Protocol funtion prototypes +// +/** + Sends an NVM Express Command Packet to an NVM Express controller or namespace. This function supports + both blocking I/O and non-blocking I/O. The blocking I/O functionality is required, and the non-blocking + I/O functionality is optional. + + + @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. + @param[in] NamespaceId A 32 bit namespace ID as defined in the NVMe specification to which the NVM Express Command + Packet will be sent. A value of 0 denotes the NVM Express controller, a value of all 0xFF's + (all bytes are 0xFF) in the namespace ID specifies that the command packet should be sent to + all valid namespaces. + @param[in,out] Packet A pointer to the NVM Express Command Packet. + @param[in] Event If non-blocking I/O is not supported then Event is ignored, and blocking I/O is performed. + If Event is NULL, then blocking I/O is performed. If Event is not NULL and non-blocking I/O + is supported, then non-blocking I/O is performed, and Event will be signaled when the NVM + Express Command Packet completes. + + @retval EFI_SUCCESS The NVM Express Command Packet was sent by the host. TransferLength bytes were transferred + to, or from DataBuffer. + @retval EFI_BAD_BUFFER_SIZE The NVM Express Command Packet was not executed. The number of bytes that could be transferred + is returned in TransferLength. + @retval EFI_NOT_READY The NVM Express Command Packet could not be sent because the controller is not ready. The caller + may retry again later. + @retval EFI_DEVICE_ERROR A device error occurred while attempting to send the NVM Express Command Packet. + @retval EFI_INVALID_PARAMETER NamespaceId or the contents of EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET are invalid. The NVM + Express Command Packet was not sent, so no additional status information is available. + @retval EFI_UNSUPPORTED The command described by the NVM Express Command Packet is not supported by the NVM Express + controller. The NVM Express Command Packet was not sent so no additional status information + is available. + @retval EFI_TIMEOUT A timeout occurred while waiting for the NVM Express Command Packet to execute. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_PASSTHRU)( + IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, + IN UINT32 NamespaceId, + IN OUT EFI_NVM_EXPRESS_PASS_THRU_COMMAND_PACKET *Packet, + IN EFI_EVENT Event OPTIONAL + ); + +/** + Used to retrieve the next namespace ID for this NVM Express controller. + + The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNextNamespace() function retrieves the next valid + namespace ID on this NVM Express controller. + + If on input the value pointed to by NamespaceId is 0xFFFFFFFF, then the first valid namespace + ID defined on the NVM Express controller is returned in the location pointed to by NamespaceId + and a status of EFI_SUCCESS is returned. + + If on input the value pointed to by NamespaceId is an invalid namespace ID other than 0xFFFFFFFF, + then EFI_INVALID_PARAMETER is returned. + + If on input the value pointed to by NamespaceId is a valid namespace ID, then the next valid + namespace ID on the NVM Express controller is returned in the location pointed to by NamespaceId, + and EFI_SUCCESS is returned. + + If the value pointed to by NamespaceId is the namespace ID of the last namespace on the NVM + Express controller, then EFI_NOT_FOUND is returned. + + @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. + @param[in,out] NamespaceId On input, a pointer to a legal NamespaceId for an NVM Express + namespace present on the NVM Express controller. On output, a + pointer to the next NamespaceId of an NVM Express namespace on + an NVM Express controller. An input value of 0xFFFFFFFF retrieves + the first NamespaceId for an NVM Express namespace present on an + NVM Express controller. + + @retval EFI_SUCCESS The Namespace ID of the next Namespace was returned. + @retval EFI_NOT_FOUND There are no more namespaces defined on this controller. + @retval EFI_INVALID_PARAMETER NamespaceId is an invalid value other than 0xFFFFFFFF. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_GET_NEXT_NAMESPACE)( + IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, + IN OUT UINT32 *NamespaceId + ); + +/** + Used to allocate and build a device path node for an NVM Express namespace on an NVM Express controller. + + The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.BuildDevicePath() function allocates and builds a single device + path node for the NVM Express namespace specified by NamespaceId. + + If the NamespaceId is not valid, then EFI_NOT_FOUND is returned. + + If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. + + If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES is returned. + + Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of DevicePath are + initialized to describe the NVM Express namespace specified by NamespaceId, and EFI_SUCCESS is returned. + + @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. + @param[in] NamespaceId The NVM Express namespace ID for which a device path node is to be + allocated and built. Caller must set the NamespaceId to zero if the + device path node will contain a valid UUID. + @param[in,out] DevicePath A pointer to a single device path node that describes the NVM Express + namespace specified by NamespaceId. This function is responsible for + allocating the buffer DevicePath with the boot service AllocatePool(). + It is the caller's responsibility to free DevicePath when the caller + is finished with DevicePath. + @retval EFI_SUCCESS The device path node that describes the NVM Express namespace specified + by NamespaceId was allocated and returned in DevicePath. + @retval EFI_NOT_FOUND The NamespaceId is not valid. + @retval EFI_INVALID_PARAMETER DevicePath is NULL. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the DevicePath node. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH)( + IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, + IN UINT32 NamespaceId, + IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath + ); + +/** + Used to translate a device path node to a namespace ID. + + The EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL.GetNamespace() function determines the namespace ID associated with the + namespace described by DevicePath. + + If DevicePath is a device path node type that the NVM Express Pass Thru driver supports, then the NVM Express + Pass Thru driver will attempt to translate the contents DevicePath into a namespace ID. + + If this translation is successful, then that namespace ID is returned in NamespaceId, and EFI_SUCCESS is returned + + @param[in] This A pointer to the EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL instance. + @param[in] DevicePath A pointer to the device path node that describes an NVM Express namespace on + the NVM Express controller. + @param[out] NamespaceId The NVM Express namespace ID contained in the device path node. + + @retval EFI_SUCCESS DevicePath was successfully translated to NamespaceId. + @retval EFI_INVALID_PARAMETER If DevicePath or NamespaceId are NULL, then EFI_INVALID_PARAMETER is returned. + @retval EFI_UNSUPPORTED If DevicePath is not a device path node type that the NVM Express Pass Thru driver + supports, then EFI_UNSUPPORTED is returned. + @retval EFI_NOT_FOUND If DevicePath is a device path node type that the NVM Express Pass Thru driver + supports, but there is not a valid translation from DevicePath to a namespace ID, + then EFI_NOT_FOUND is returned. +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_NVM_EXPRESS_PASS_THRU_GET_NAMESPACE)( + IN EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL *This, + IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, + OUT UINT32 *NamespaceId + ); + +// +// Protocol Interface Structure +// +struct _EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL { + EFI_NVM_EXPRESS_PASS_THRU_MODE *Mode; + EFI_NVM_EXPRESS_PASS_THRU_PASSTHRU PassThru; + EFI_NVM_EXPRESS_PASS_THRU_GET_NEXT_NAMESPACE GetNextNamespace; + EFI_NVM_EXPRESS_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath; + EFI_NVM_EXPRESS_PASS_THRU_GET_NAMESPACE GetNamespace; +}; + +extern EFI_GUID gEfiNvmExpressPassThruProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/SmartCardEdge.h b/MdePkg/Include/Protocol/SmartCardEdge.h index ac5095c375..d3dbb540ad 100644 --- a/MdePkg/Include/Protocol/SmartCardEdge.h +++ b/MdePkg/Include/Protocol/SmartCardEdge.h @@ -1,739 +1,739 @@ -/** @file - The Smart Card Edge Protocol provides an abstraction for device to provide Smart - Card support. - - This protocol allows UEFI applications to interface with a Smart Card during - boot process for authentication or data signing/decryption, especially if the - application has to make use of PKI. - - Copyright (c) 2015, Intel Corporation. All rights reserved.
- This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef __SMART_CARD_EDGE_H__ -#define __SMART_CARD_EDGE_H__ - -#define EFI_SMART_CARD_EDGE_PROTOCOL_GUID \ - { \ - 0xd317f29b, 0xa325, 0x4712, {0x9b, 0xf1, 0xc6, 0x19, 0x54, 0xdc, 0x19, 0x8c} \ - } - -typedef struct _EFI_SMART_CARD_EDGE_PROTOCOL EFI_SMART_CARD_EDGE_PROTOCOL; - -// -// Maximum size for a Smart Card AID (Application IDentifier) -// -#define SCARD_AID_MAXSIZE 0x0010 -// -// Size of CSN (Card Serial Number) -// -#define SCARD_CSN_SIZE 0x0010 -// -// Current specification version 1.00 -// -#define SMART_CARD_EDGE_PROTOCOL_VERSION_1 0x00000100 -// -// Parameters type definition -// -typedef UINT8 SMART_CARD_AID[SCARD_AID_MAXSIZE]; -typedef UINT8 SMART_CARD_CSN[SCARD_CSN_SIZE]; - -// -// Type of data elements in credentials list -// -// value of tag field for header, the number of containers -// -#define SC_EDGE_TAG_HEADER 0x0000 -// -// value of tag field for certificate -// -#define SC_EDGE_TAG_CERT 0x0001 -// -// value of tag field for key index associated with certificate -// -#define SC_EDGE_TAG_KEY_ID 0x0002 -// -// value of tag field for key type -// -#define SC_EDGE_TAG_KEY_TYPE 0x0003 -// -// value of tag field for key size -// -#define SC_EDGE_TAG_KEY_SIZE 0x0004 - -// -// Length of L fields of TLV items -// -// -// size of L field for header -// -#define SC_EDGE_L_SIZE_HEADER 1 -// -// size of L field for certificate (big endian) -// -#define SC_EDGE_L_SIZE_CERT 2 -// -// size of L field for key index -// -#define SC_EDGE_L_SIZE_KEY_ID 1 -// -// size of L field for key type -// -#define SC_EDGE_L_SIZE_KEY_TYPE 1 -// -// size of L field for key size (big endian) -// -#define SC_EDGE_L_SIZE_KEY_SIZE 2 - -// -// Some TLV items have a fixed value for L field -// -// value of L field for header -// -#define SC_EDGE_L_VALUE_HEADER 1 -// -// value of L field for key index -// -#define SC_EDGE_L_VALUE_KEY_ID 1 -// -// value of L field for key type -// -#define SC_EDGE_L_VALUE_KEY_TYPE 1 -// -// value of L field for key size -// -#define SC_EDGE_L_VALUE_KEY_SIZE 2 - -// -// Possible values for key type -// -// -// RSA decryption -// -#define SC_EDGE_RSA_EXCHANGE 0x01 -// -// RSA signature -// -#define SC_EDGE_RSA_SIGNATURE 0x02 -// -// ECDSA signature -// -#define SC_EDGE_ECDSA_256 0x03 -// -// ECDSA signature -// -#define SC_EDGE_ECDSA_384 0x04 -// -// ECDSA signature -// -#define SC_EDGE_ECDSA_521 0x05 -// -// ECDH agreement -// -#define SC_EDGE_ECDH_256 0x06 -// -// ECDH agreement -// -#define SC_EDGE_ECDH_384 0x07 -// -// ECDH agreement -// -#define SC_EDGE_ECDH_521 0x08 - -// -// Padding methods GUIDs for signature -// -// -// RSASSA- PKCS#1-V1.5 padding method, for signature -// -#define EFI_PADDING_RSASSA_PKCS1V1P5_GUID \ - { \ - 0x9317ec24, 0x7cb0, 0x4d0e, {0x8b, 0x32, 0x2e, 0xd9, 0x20, 0x9c, 0xd8, 0xaf} \ - } - -extern EFI_GUID gEfiPaddingRsassaPkcs1V1P5Guid; - -// -// RSASSA-PSS padding method, for signature -// -#define EFI_PADDING_RSASSA_PSS_GUID \ - { \ - 0x7b2349e0, 0x522d, 0x4f8e, {0xb9, 0x27, 0x69, 0xd9, 0x7c, 0x9e, 0x79, 0x5f} \ - } - -extern EFI_GUID gEfiPaddingRsassaPssGuid; - -// -// Padding methods GUIDs for decryption -// -// -// No padding, for decryption -// -#define EFI_PADDING_NONE_GUID \ - { \ - 0x3629ddb1, 0x228c, 0x452e, {0xb6, 0x16, 0x09, 0xed, 0x31, 0x6a, 0x97, 0x00} \ - } - -extern EFI_GUID gEfiPaddingNoneGuid; - -// -// RSAES-PKCS#1-V1.5 padding, for decryption -// -#define EFI_PADDING_RSAES_PKCS1V1P5_GUID \ - { \ - 0xe1c1d0a9, 0x40b1, 0x4632, {0xbd, 0xcc, 0xd9, 0xd6, 0xe5, 0x29, 0x56, 0x31} \ - } - -extern EFI_GUID gEfiPaddingRsaesPkcs1V1P5Guid; - -// -// RSAES-OAEP padding, for decryption -// -#define EFI_PADDING_RSAES_OAEP_GUID \ - { \ - 0xc1e63ac4, 0xd0cf, 0x4ce6, {0x83, 0x5b, 0xee, 0xd0, 0xe6, 0xa8, 0xa4, 0x5b} \ - } - -extern EFI_GUID gEfiPaddingRsaesOaepGuid; - -/** - This function retrieves the context driver. - - The GetContextfunction returns the context of the protocol, the application - identifiers supported by the protocol and the number and the CSN unique identifier - of Smart Cards that are present and supported by protocol. - - If AidTableSize, AidTable, CsnTableSize, CsnTable or VersionProtocol is NULL, - the function does not fail but does not fill in such variables. - - In case AidTableSize indicates a buffer too small to hold all the protocol AID table, - only the first AidTableSize items of the table are returned in AidTable. - - In case CsnTableSize indicates a buffer too small to hold the entire table of - Smart Card CSN present, only the first CsnTableSize items of the table are returned - in CsnTable. - - VersionScEdgeProtocol returns the version of the EFI_SMART_CARD_EDGE_PROTOCOL this - driver uses. For this protocol specification value is SMART_CARD_EDGE_PROTOCOL_VERSION_1. - - In case of Smart Card removal the internal CSN list is immediately updated, even if - a connection is opened with that Smart Card. - - @param[in] This Indicates a pointer to the calling context. - @param[out] NumberAidSupported Number of AIDs this protocol supports. - @param[in, out] AidTableSize On input, number of items allocated for the - AID table. On output, number of items returned - by protocol. - @param[out] AidTable Table of the AIDs supported by the protocol. - @param[out] NumberSCPresent Number of currently present Smart Cards that - are supported by protocol. - @param[in, out] CsnTableSize On input, the number of items the buffer CSN - table can contain. On output, the number of - items returned by the protocol. - @param[out] CsnTable Table of the CSN of the Smart Card present and - supported by protocol. - @param[out] VersionScEdgeProtocol EFI_SMART_CARD_EDGE_PROTOCOL version. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER NumberSCPresent is NULL. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_GET_CONTEXT) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - OUT UINTN *NumberAidSupported, - IN OUT UINTN *AidTableSize OPTIONAL, - OUT SMART_CARD_AID *AidTable OPTIONAL, - OUT UINTN *NumberSCPresent, - IN OUT UINTN *CsnTableSize OPTIONAL, - OUT SMART_CARD_CSN *CsnTable OPTIONAL, - OUT UINT32 *VersionScEdgeProtocol OPTIONAL - ); - -/** - This function establish a connection with a Smart Card the protocol support. - - In case of success the SCardHandle can be used. - - If the ScardCsn is NULL the connection is established with the first Smart Card - the protocol finds in its table of Smart Card present and supported. Else it - establish context with the Smart Card whose CSN given by ScardCsn. - - If ScardAid is not NULL the function returns the Smart Card AID the protocol supports. - After a successful connect the SCardHandle will remain existing even in case Smart Card - removed from Smart Card reader, but all function invoking this SCardHandle will fail. - SCardHandle is released only on Disconnect. - - @param[in] This Indicates a pointer to the calling context. - @param[out] SCardHandle Handle on Smart Card connection. - @param[in] ScardCsn CSN of the Smart Card the connection has to be - established. - @param[out] ScardAid AID of the Smart Card the connection has been - established. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER SCardHandle is NULL. - @retval EFI_NO_MEDIA No Smart Card supported by protocol is present, - Smart Card with CSN ScardCsn or Reader has been - removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_CONNECT) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - OUT EFI_HANDLE *SCardHandle, - IN UINT8 *ScardCsn OPTIONAL, - OUT UINT8 *ScardAid OPTIONAL - ); - -/** - This function releases a connection previously established by Connect. - - The Disconnect function releases the connection previously established by - a Connect. In case the Smart Card or the Smart Card reader has been removed - before this call, this function returns EFI_SUCCESS. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection to release. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_DISCONNECT) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle - ); - -/** - This function returns the Smart Card serial number. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[out] Csn The Card Serial number, 16 bytes array. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_GET_CSN) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - OUT UINT8 Csn[SCARD_CSN_SIZE] - ); - -/** - This function returns the name of the Smart Card reader used for this connection. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in, out] ReaderNameLength On input, a pointer to the variable that holds - the maximal size, in bytes, of ReaderName. - On output, the required size, in bytes, for ReaderName. - @param[out] ReaderName A pointer to a NULL terminated string that will - contain the reader name. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER ReaderNameLength is NULL. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_GET_READER_NAME) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN OUT UINTN *ReaderNameLength, - OUT CHAR16 *ReaderName OPTIONAL - ); - -/** - This function authenticates a Smart Card user by presenting a PIN code. - - The VerifyPinfunction presents a PIN code to the Smart Card. - - If Smart Card found the PIN code correct the user is considered authenticated - to current application, and the function returns TRUE. - - Negative or null PinSize value rejected if PinCodeis not NULL. - - A NULL PinCodebuffer means the application didn't know the PIN, in that case: - - If PinSize value is negative the caller only wants to know if the current - chain of the elements Smart Card Edge protocol, Smart Card Reader protocol - and Smart Card Reader supports the Secure Pin Entry PCSC V2 functionality. - - If PinSize value is positive or null the caller ask to perform the verify - PIN using the Secure PIN Entry functionality. - - In PinCode buffer, the PIN value is always given in plaintext, in case of secure - messaging the SMART_CARD_EDGE_PROTOCOL will be in charge of all intermediate - treatments to build the correct Smart Card APDU. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in] PinSize PIN code buffer size. - @param[in] PinCode PIN code to present to the Smart Card. - @param[out] PinResult Result of PIN code presentation to the Smart Card. - TRUE when Smard Card founds the PIN code correct. - @param[out] RemainingAttempts Number of attempts still possible. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_UNSUPPORTED Pinsize < 0 and Secure PIN Entry functionality not - supported. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER Bad value for PinSize: value not supported by Smart - Card or, negative with PinCode not null. - @retval EFI_INVALID_PARAMETER PinResult is NULL. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_VERIFY_PIN) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN INT32 PinSize, - IN UINT8 *PinCode, - OUT BOOLEAN *PinResult, - OUT UINT32 *RemainingAttempts OPTIONAL - ); - -/** - This function gives the remaining number of attempts for PIN code presentation. - - The number of attempts to present a correct PIN is limited and depends on Smart - Card and on PIN. - - This function will retrieve the number of remaining possible attempts. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[out] RemainingAttempts Number of attempts still possible. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER RemainingAttempts is NULL. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_GET_PIN_REMAINING) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - OUT UINT32 *RemainingAttempts - ); - -/** - This function returns a specific data from Smart Card. - - The function is generic for any kind of data, but driver and application must - share an EFI_GUID that identify the data. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in] DataId The type identifier of the data to get. - @param[in, out] DataSize On input, in bytes, the size of Data. On output, - in bytes, the size of buffer required to store - the specified data. - @param[out] Data The data buffer in which the data is returned. - The type of the data buffer is associated with - the DataId. Ignored if *DataSize is 0. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER DataId is NULL. - @retval EFI_INVALID_PARAMETER DataSize is NULL. - @retval EFI_INVALID_PARAMETER Data is NULL, and *DataSize is not zero. - @retval EFI_NOT_FOUND DataId unknown for this driver. - @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified - data and the required size is returned in DataSize. - @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. - PIN not verified. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_GET_DATA) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN EFI_GUID *DataId, - IN OUT UINTN *DataSize, - OUT VOID *Data OPTIONAL - ); - -/** - This function retrieve credentials store into the Smart Card. - - The function returns a series of items in TLV (Tag Length Value) format. - - First TLV item is the header item that gives the number of following - containers (0x00, 0x01, Nb containers). - - All these containers are a series of 4 TLV items: - - The certificate item (0x01, certificate size, certificate) - - The Key identifier item (0x02, 0x01, key index) - - The key type item (0x03, 0x01, key type) - - The key size item (0x04, 0x02, key size), key size in number of bits. - Numeric multi-bytes values are on big endian format, most significant byte first: - - The L field value for certificate (2 bytes) - - The L field value for key size (2 bytes) - - The value field for key size (2 bytes) - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in, out] CredentialSize On input, in bytes, the size of buffer to store - the list of credential. - On output, in bytes, the size of buffer required - to store the entire list of credentials. - - @param[out] CredentialList List of credentials stored into the Smart Card. - A list of TLV (Tag Length Value) elements organized - in containers array. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER CredentialSize is NULL. - @retval EFI_INVALID_PARAMETER CredentialList is NULL, if CredentialSize is not zero. - @retval EFI_BUFFER_TOO_SMALL The size of CredentialList is too small for the - specified data and the required size is returned in - CredentialSize. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_GET_CREDENTIAL) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN OUT UINTN *CredentialSize, - OUT UINT8 *CredentialList OPTIONAL - ); - -/** - This function signs an already hashed data with a Smart Card private key. - - This function signs data, actually it is the hash of these data that is given - to the function. - - SignatureData buffer shall be big enough for signature. Signature size is - function key size and key type. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in] KeyId Identifier of the key container, retrieved - in a key index item of credentials. - @param[in] KeyType The key type, retrieved in a key type item of - credentials. - - @param[in] HashAlgorithm Hash algorithm used to hash the, one of: - - EFI_HASH_ALGORITHM_SHA1_GUID - - EFI_HASH_ALGORITHM_SHA256_GUID - - EFI_HASH_ALGORITHM_SHA384_GUID - - EFI_HASH_ALGORITHM_SHA512_GUID - @param[in] PaddingMethod Padding method used jointly with hash algorithm, - one of: - - EFI_PADDING_RSASSA_PKCS1V1P5_GUID - - EFI_PADDING_RSASSA_PSS_GUID - @param[in] HashedData Hash of the data to sign. Size is function of the - HashAlgorithm. - - @param[out] SignatureData Resulting signature with private key KeyId. Size - is function of the KeyType and key size retrieved - in the associated key size item of credentials. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER KeyId is not valid. - @retval EFI_INVALID_PARAMETER KeyType is not valid or not corresponding to KeyId. - @retval EFI_INVALID_PARAMETER HashAlgorithm is NULL. - @retval EFI_INVALID_PARAMETER HashAlgorithm is not valid. - @retval EFI_INVALID_PARAMETER PaddingMethod is NULL. - @retval EFI_INVALID_PARAMETER PaddingMethod is not valid. - @retval EFI_INVALID_PARAMETER HashedData is NULL. - @retval EFI_INVALID_PARAMETER SignatureData is NULL. - @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. - PIN not verified. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_SIGN_DATA) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN UINTN KeyId, - IN UINTN KeyType, - IN EFI_GUID *HashAlgorithm, - IN EFI_GUID *PaddingMethod, - IN UINT8 *HashedData, - OUT UINT8 *SignatureData - ); - -/** - This function decrypts data with a PKI/RSA Smart Card private key. - - The function decrypts some PKI/RSA encrypted data with private key securely - stored into the Smart Card. - - The KeyId must reference a key of type SC_EDGE_RSA_EXCHANGE. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in] KeyId Identifier of the key container, retrieved - in a key index item of credentials. - @param[in] HashAlgorithm Hash algorithm used to hash the, one of: - - EFI_HASH_ALGORITHM_SHA1_GUID - - EFI_HASH_ALGORITHM_SHA256_GUID - - EFI_HASH_ALGORITHM_SHA384_GUID - - EFI_HASH_ALGORITHM_SHA512_GUID - @param[in] PaddingMethod Padding method used jointly with hash algorithm, - one of: - - EFI_PADDING_NONE_GUID - - EFI_PADDING_RSAES_PKCS1V1P5_GUID - - EFI_PADDING_RSAES_OAEP_GUID - @param[in] EncryptedSize Size of data to decrypt. - @param[in] EncryptedData Data to decrypt - @param[in, out] PlaintextSize On input, in bytes, the size of buffer to store - the decrypted data. - On output, in bytes, the size of buffer required - to store the decrypted data. - @param[out] PlaintextData Buffer for decrypted data, padding removed. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER KeyId is not valid or associated key not of type - SC_EDGE_RSA_EXCHANGE. - @retval EFI_INVALID_PARAMETER HashAlgorithm is NULL. - @retval EFI_INVALID_PARAMETER HashAlgorithm is not valid. - @retval EFI_INVALID_PARAMETER PaddingMethod is NULL. - @retval EFI_INVALID_PARAMETER PaddingMethod is not valid. - @retval EFI_INVALID_PARAMETER EncryptedSize is 0. - @retval EFI_INVALID_PARAMETER EncryptedData is NULL. - @retval EFI_INVALID_PARAMETER PlaintextSize is NULL. - @retval EFI_INVALID_PARAMETER PlaintextData is NULL. - @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. - PIN not verified. - @retval EFI_BUFFER_TOO_SMALL PlaintextSize is too small for the plaintext data - and the required size is returned in PlaintextSize. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_DECRYPT_DATA) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN UINTN KeyId, - IN EFI_GUID *HashAlgorithm, - IN EFI_GUID *PaddingMethod, - IN UINTN EncryptedSize, - IN UINT8 *EncryptedData, - IN OUT UINTN *PlaintextSize, - OUT UINT8 *PlaintextData - ); - -/** - This function performs a secret Diffie Hellman agreement calculation that would - be used to derive a symmetric encryption / decryption key. - - The function compute a DH agreement that should be diversified togenerate a symmetric - key to proceed encryption or decryption. - - The application and the Smart Card shall agree on the diversification process. - - The KeyId must reference a key of one of the types: SC_EDGE_ECDH_256, SC_EDGE_ECDH_384 - or SC_EDGE_ECDH_521. - - @param[in] This Indicates a pointer to the calling context. - @param[in] SCardHandle Handle on Smart Card connection. - @param[in] KeyId Identifier of the key container, retrieved - in a key index item of credentials. - @param[in] dataQx Public key x coordinate. Size is the same as - key size for KeyId. Stored in big endian format. - @param[in] dataQy Public key y coordinate. Size is the same as - key size for KeyId. Stored in big endian format. - @param[out] DHAgreement Buffer for DH agreement computed. Size must be - bigger or equal to key size for KeyId. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. - @retval EFI_INVALID_PARAMETER KeyId is not valid. - @retval EFI_INVALID_PARAMETER dataQx is NULL. - @retval EFI_INVALID_PARAMETER dataQy is NULL. - @retval EFI_INVALID_PARAMETER DHAgreement is NULL. - @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. - PIN not verified. - @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection - has been removed. A Disconnect should be performed. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT) ( - IN EFI_SMART_CARD_EDGE_PROTOCOL *This, - IN EFI_HANDLE SCardHandle, - IN UINTN KeyId, - IN UINT8 *dataQx, - IN UINT8 *dataQy, - OUT UINT8 *DHAgreement - ); - -/// -/// Smart card aware application invokes this protocol to get access to an inserted -/// smart card in the reader or to the reader itself. -/// -struct _EFI_SMART_CARD_EDGE_PROTOCOL { - EFI_SMART_CARD_EDGE_GET_CONTEXT GetContext; - EFI_SMART_CARD_EDGE_CONNECT Connect; - EFI_SMART_CARD_EDGE_DISCONNECT Disconnect; - EFI_SMART_CARD_EDGE_GET_CSN GetCsn; - EFI_SMART_CARD_EDGE_GET_READER_NAME GetReaderName; - EFI_SMART_CARD_EDGE_VERIFY_PIN VerifyPin; - EFI_SMART_CARD_EDGE_GET_PIN_REMAINING GetPinRemaining; - EFI_SMART_CARD_EDGE_GET_DATA GetData; - EFI_SMART_CARD_EDGE_GET_CREDENTIAL GetCredential; - EFI_SMART_CARD_EDGE_SIGN_DATA SignData; - EFI_SMART_CARD_EDGE_DECRYPT_DATA DecryptData; - EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT BuildDHAgreement; -}; - -extern EFI_GUID gEfiSmartCardEdgeProtocolGuid; - -#endif - +/** @file + The Smart Card Edge Protocol provides an abstraction for device to provide Smart + Card support. + + This protocol allows UEFI applications to interface with a Smart Card during + boot process for authentication or data signing/decryption, especially if the + application has to make use of PKI. + + Copyright (c) 2015, Intel Corporation. All rights reserved.
+ This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef __SMART_CARD_EDGE_H__ +#define __SMART_CARD_EDGE_H__ + +#define EFI_SMART_CARD_EDGE_PROTOCOL_GUID \ + { \ + 0xd317f29b, 0xa325, 0x4712, {0x9b, 0xf1, 0xc6, 0x19, 0x54, 0xdc, 0x19, 0x8c} \ + } + +typedef struct _EFI_SMART_CARD_EDGE_PROTOCOL EFI_SMART_CARD_EDGE_PROTOCOL; + +// +// Maximum size for a Smart Card AID (Application IDentifier) +// +#define SCARD_AID_MAXSIZE 0x0010 +// +// Size of CSN (Card Serial Number) +// +#define SCARD_CSN_SIZE 0x0010 +// +// Current specification version 1.00 +// +#define SMART_CARD_EDGE_PROTOCOL_VERSION_1 0x00000100 +// +// Parameters type definition +// +typedef UINT8 SMART_CARD_AID[SCARD_AID_MAXSIZE]; +typedef UINT8 SMART_CARD_CSN[SCARD_CSN_SIZE]; + +// +// Type of data elements in credentials list +// +// value of tag field for header, the number of containers +// +#define SC_EDGE_TAG_HEADER 0x0000 +// +// value of tag field for certificate +// +#define SC_EDGE_TAG_CERT 0x0001 +// +// value of tag field for key index associated with certificate +// +#define SC_EDGE_TAG_KEY_ID 0x0002 +// +// value of tag field for key type +// +#define SC_EDGE_TAG_KEY_TYPE 0x0003 +// +// value of tag field for key size +// +#define SC_EDGE_TAG_KEY_SIZE 0x0004 + +// +// Length of L fields of TLV items +// +// +// size of L field for header +// +#define SC_EDGE_L_SIZE_HEADER 1 +// +// size of L field for certificate (big endian) +// +#define SC_EDGE_L_SIZE_CERT 2 +// +// size of L field for key index +// +#define SC_EDGE_L_SIZE_KEY_ID 1 +// +// size of L field for key type +// +#define SC_EDGE_L_SIZE_KEY_TYPE 1 +// +// size of L field for key size (big endian) +// +#define SC_EDGE_L_SIZE_KEY_SIZE 2 + +// +// Some TLV items have a fixed value for L field +// +// value of L field for header +// +#define SC_EDGE_L_VALUE_HEADER 1 +// +// value of L field for key index +// +#define SC_EDGE_L_VALUE_KEY_ID 1 +// +// value of L field for key type +// +#define SC_EDGE_L_VALUE_KEY_TYPE 1 +// +// value of L field for key size +// +#define SC_EDGE_L_VALUE_KEY_SIZE 2 + +// +// Possible values for key type +// +// +// RSA decryption +// +#define SC_EDGE_RSA_EXCHANGE 0x01 +// +// RSA signature +// +#define SC_EDGE_RSA_SIGNATURE 0x02 +// +// ECDSA signature +// +#define SC_EDGE_ECDSA_256 0x03 +// +// ECDSA signature +// +#define SC_EDGE_ECDSA_384 0x04 +// +// ECDSA signature +// +#define SC_EDGE_ECDSA_521 0x05 +// +// ECDH agreement +// +#define SC_EDGE_ECDH_256 0x06 +// +// ECDH agreement +// +#define SC_EDGE_ECDH_384 0x07 +// +// ECDH agreement +// +#define SC_EDGE_ECDH_521 0x08 + +// +// Padding methods GUIDs for signature +// +// +// RSASSA- PKCS#1-V1.5 padding method, for signature +// +#define EFI_PADDING_RSASSA_PKCS1V1P5_GUID \ + { \ + 0x9317ec24, 0x7cb0, 0x4d0e, {0x8b, 0x32, 0x2e, 0xd9, 0x20, 0x9c, 0xd8, 0xaf} \ + } + +extern EFI_GUID gEfiPaddingRsassaPkcs1V1P5Guid; + +// +// RSASSA-PSS padding method, for signature +// +#define EFI_PADDING_RSASSA_PSS_GUID \ + { \ + 0x7b2349e0, 0x522d, 0x4f8e, {0xb9, 0x27, 0x69, 0xd9, 0x7c, 0x9e, 0x79, 0x5f} \ + } + +extern EFI_GUID gEfiPaddingRsassaPssGuid; + +// +// Padding methods GUIDs for decryption +// +// +// No padding, for decryption +// +#define EFI_PADDING_NONE_GUID \ + { \ + 0x3629ddb1, 0x228c, 0x452e, {0xb6, 0x16, 0x09, 0xed, 0x31, 0x6a, 0x97, 0x00} \ + } + +extern EFI_GUID gEfiPaddingNoneGuid; + +// +// RSAES-PKCS#1-V1.5 padding, for decryption +// +#define EFI_PADDING_RSAES_PKCS1V1P5_GUID \ + { \ + 0xe1c1d0a9, 0x40b1, 0x4632, {0xbd, 0xcc, 0xd9, 0xd6, 0xe5, 0x29, 0x56, 0x31} \ + } + +extern EFI_GUID gEfiPaddingRsaesPkcs1V1P5Guid; + +// +// RSAES-OAEP padding, for decryption +// +#define EFI_PADDING_RSAES_OAEP_GUID \ + { \ + 0xc1e63ac4, 0xd0cf, 0x4ce6, {0x83, 0x5b, 0xee, 0xd0, 0xe6, 0xa8, 0xa4, 0x5b} \ + } + +extern EFI_GUID gEfiPaddingRsaesOaepGuid; + +/** + This function retrieves the context driver. + + The GetContextfunction returns the context of the protocol, the application + identifiers supported by the protocol and the number and the CSN unique identifier + of Smart Cards that are present and supported by protocol. + + If AidTableSize, AidTable, CsnTableSize, CsnTable or VersionProtocol is NULL, + the function does not fail but does not fill in such variables. + + In case AidTableSize indicates a buffer too small to hold all the protocol AID table, + only the first AidTableSize items of the table are returned in AidTable. + + In case CsnTableSize indicates a buffer too small to hold the entire table of + Smart Card CSN present, only the first CsnTableSize items of the table are returned + in CsnTable. + + VersionScEdgeProtocol returns the version of the EFI_SMART_CARD_EDGE_PROTOCOL this + driver uses. For this protocol specification value is SMART_CARD_EDGE_PROTOCOL_VERSION_1. + + In case of Smart Card removal the internal CSN list is immediately updated, even if + a connection is opened with that Smart Card. + + @param[in] This Indicates a pointer to the calling context. + @param[out] NumberAidSupported Number of AIDs this protocol supports. + @param[in, out] AidTableSize On input, number of items allocated for the + AID table. On output, number of items returned + by protocol. + @param[out] AidTable Table of the AIDs supported by the protocol. + @param[out] NumberSCPresent Number of currently present Smart Cards that + are supported by protocol. + @param[in, out] CsnTableSize On input, the number of items the buffer CSN + table can contain. On output, the number of + items returned by the protocol. + @param[out] CsnTable Table of the CSN of the Smart Card present and + supported by protocol. + @param[out] VersionScEdgeProtocol EFI_SMART_CARD_EDGE_PROTOCOL version. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER NumberSCPresent is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_GET_CONTEXT) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + OUT UINTN *NumberAidSupported, + IN OUT UINTN *AidTableSize OPTIONAL, + OUT SMART_CARD_AID *AidTable OPTIONAL, + OUT UINTN *NumberSCPresent, + IN OUT UINTN *CsnTableSize OPTIONAL, + OUT SMART_CARD_CSN *CsnTable OPTIONAL, + OUT UINT32 *VersionScEdgeProtocol OPTIONAL + ); + +/** + This function establish a connection with a Smart Card the protocol support. + + In case of success the SCardHandle can be used. + + If the ScardCsn is NULL the connection is established with the first Smart Card + the protocol finds in its table of Smart Card present and supported. Else it + establish context with the Smart Card whose CSN given by ScardCsn. + + If ScardAid is not NULL the function returns the Smart Card AID the protocol supports. + After a successful connect the SCardHandle will remain existing even in case Smart Card + removed from Smart Card reader, but all function invoking this SCardHandle will fail. + SCardHandle is released only on Disconnect. + + @param[in] This Indicates a pointer to the calling context. + @param[out] SCardHandle Handle on Smart Card connection. + @param[in] ScardCsn CSN of the Smart Card the connection has to be + established. + @param[out] ScardAid AID of the Smart Card the connection has been + established. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER SCardHandle is NULL. + @retval EFI_NO_MEDIA No Smart Card supported by protocol is present, + Smart Card with CSN ScardCsn or Reader has been + removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_CONNECT) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + OUT EFI_HANDLE *SCardHandle, + IN UINT8 *ScardCsn OPTIONAL, + OUT UINT8 *ScardAid OPTIONAL + ); + +/** + This function releases a connection previously established by Connect. + + The Disconnect function releases the connection previously established by + a Connect. In case the Smart Card or the Smart Card reader has been removed + before this call, this function returns EFI_SUCCESS. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection to release. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_DISCONNECT) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle + ); + +/** + This function returns the Smart Card serial number. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[out] Csn The Card Serial number, 16 bytes array. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_GET_CSN) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + OUT UINT8 Csn[SCARD_CSN_SIZE] + ); + +/** + This function returns the name of the Smart Card reader used for this connection. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in, out] ReaderNameLength On input, a pointer to the variable that holds + the maximal size, in bytes, of ReaderName. + On output, the required size, in bytes, for ReaderName. + @param[out] ReaderName A pointer to a NULL terminated string that will + contain the reader name. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER ReaderNameLength is NULL. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_GET_READER_NAME) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN OUT UINTN *ReaderNameLength, + OUT CHAR16 *ReaderName OPTIONAL + ); + +/** + This function authenticates a Smart Card user by presenting a PIN code. + + The VerifyPinfunction presents a PIN code to the Smart Card. + + If Smart Card found the PIN code correct the user is considered authenticated + to current application, and the function returns TRUE. + + Negative or null PinSize value rejected if PinCodeis not NULL. + + A NULL PinCodebuffer means the application didn't know the PIN, in that case: + - If PinSize value is negative the caller only wants to know if the current + chain of the elements Smart Card Edge protocol, Smart Card Reader protocol + and Smart Card Reader supports the Secure Pin Entry PCSC V2 functionality. + - If PinSize value is positive or null the caller ask to perform the verify + PIN using the Secure PIN Entry functionality. + + In PinCode buffer, the PIN value is always given in plaintext, in case of secure + messaging the SMART_CARD_EDGE_PROTOCOL will be in charge of all intermediate + treatments to build the correct Smart Card APDU. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in] PinSize PIN code buffer size. + @param[in] PinCode PIN code to present to the Smart Card. + @param[out] PinResult Result of PIN code presentation to the Smart Card. + TRUE when Smard Card founds the PIN code correct. + @param[out] RemainingAttempts Number of attempts still possible. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_UNSUPPORTED Pinsize < 0 and Secure PIN Entry functionality not + supported. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER Bad value for PinSize: value not supported by Smart + Card or, negative with PinCode not null. + @retval EFI_INVALID_PARAMETER PinResult is NULL. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_VERIFY_PIN) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN INT32 PinSize, + IN UINT8 *PinCode, + OUT BOOLEAN *PinResult, + OUT UINT32 *RemainingAttempts OPTIONAL + ); + +/** + This function gives the remaining number of attempts for PIN code presentation. + + The number of attempts to present a correct PIN is limited and depends on Smart + Card and on PIN. + + This function will retrieve the number of remaining possible attempts. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[out] RemainingAttempts Number of attempts still possible. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER RemainingAttempts is NULL. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_GET_PIN_REMAINING) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + OUT UINT32 *RemainingAttempts + ); + +/** + This function returns a specific data from Smart Card. + + The function is generic for any kind of data, but driver and application must + share an EFI_GUID that identify the data. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in] DataId The type identifier of the data to get. + @param[in, out] DataSize On input, in bytes, the size of Data. On output, + in bytes, the size of buffer required to store + the specified data. + @param[out] Data The data buffer in which the data is returned. + The type of the data buffer is associated with + the DataId. Ignored if *DataSize is 0. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER DataId is NULL. + @retval EFI_INVALID_PARAMETER DataSize is NULL. + @retval EFI_INVALID_PARAMETER Data is NULL, and *DataSize is not zero. + @retval EFI_NOT_FOUND DataId unknown for this driver. + @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified + data and the required size is returned in DataSize. + @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. + PIN not verified. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_GET_DATA) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN EFI_GUID *DataId, + IN OUT UINTN *DataSize, + OUT VOID *Data OPTIONAL + ); + +/** + This function retrieve credentials store into the Smart Card. + + The function returns a series of items in TLV (Tag Length Value) format. + + First TLV item is the header item that gives the number of following + containers (0x00, 0x01, Nb containers). + + All these containers are a series of 4 TLV items: + - The certificate item (0x01, certificate size, certificate) + - The Key identifier item (0x02, 0x01, key index) + - The key type item (0x03, 0x01, key type) + - The key size item (0x04, 0x02, key size), key size in number of bits. + Numeric multi-bytes values are on big endian format, most significant byte first: + - The L field value for certificate (2 bytes) + - The L field value for key size (2 bytes) + - The value field for key size (2 bytes) + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in, out] CredentialSize On input, in bytes, the size of buffer to store + the list of credential. + On output, in bytes, the size of buffer required + to store the entire list of credentials. + + @param[out] CredentialList List of credentials stored into the Smart Card. + A list of TLV (Tag Length Value) elements organized + in containers array. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER CredentialSize is NULL. + @retval EFI_INVALID_PARAMETER CredentialList is NULL, if CredentialSize is not zero. + @retval EFI_BUFFER_TOO_SMALL The size of CredentialList is too small for the + specified data and the required size is returned in + CredentialSize. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_GET_CREDENTIAL) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN OUT UINTN *CredentialSize, + OUT UINT8 *CredentialList OPTIONAL + ); + +/** + This function signs an already hashed data with a Smart Card private key. + + This function signs data, actually it is the hash of these data that is given + to the function. + + SignatureData buffer shall be big enough for signature. Signature size is + function key size and key type. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in] KeyId Identifier of the key container, retrieved + in a key index item of credentials. + @param[in] KeyType The key type, retrieved in a key type item of + credentials. + + @param[in] HashAlgorithm Hash algorithm used to hash the, one of: + - EFI_HASH_ALGORITHM_SHA1_GUID + - EFI_HASH_ALGORITHM_SHA256_GUID + - EFI_HASH_ALGORITHM_SHA384_GUID + - EFI_HASH_ALGORITHM_SHA512_GUID + @param[in] PaddingMethod Padding method used jointly with hash algorithm, + one of: + - EFI_PADDING_RSASSA_PKCS1V1P5_GUID + - EFI_PADDING_RSASSA_PSS_GUID + @param[in] HashedData Hash of the data to sign. Size is function of the + HashAlgorithm. + + @param[out] SignatureData Resulting signature with private key KeyId. Size + is function of the KeyType and key size retrieved + in the associated key size item of credentials. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER KeyId is not valid. + @retval EFI_INVALID_PARAMETER KeyType is not valid or not corresponding to KeyId. + @retval EFI_INVALID_PARAMETER HashAlgorithm is NULL. + @retval EFI_INVALID_PARAMETER HashAlgorithm is not valid. + @retval EFI_INVALID_PARAMETER PaddingMethod is NULL. + @retval EFI_INVALID_PARAMETER PaddingMethod is not valid. + @retval EFI_INVALID_PARAMETER HashedData is NULL. + @retval EFI_INVALID_PARAMETER SignatureData is NULL. + @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. + PIN not verified. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_SIGN_DATA) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN UINTN KeyId, + IN UINTN KeyType, + IN EFI_GUID *HashAlgorithm, + IN EFI_GUID *PaddingMethod, + IN UINT8 *HashedData, + OUT UINT8 *SignatureData + ); + +/** + This function decrypts data with a PKI/RSA Smart Card private key. + + The function decrypts some PKI/RSA encrypted data with private key securely + stored into the Smart Card. + + The KeyId must reference a key of type SC_EDGE_RSA_EXCHANGE. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in] KeyId Identifier of the key container, retrieved + in a key index item of credentials. + @param[in] HashAlgorithm Hash algorithm used to hash the, one of: + - EFI_HASH_ALGORITHM_SHA1_GUID + - EFI_HASH_ALGORITHM_SHA256_GUID + - EFI_HASH_ALGORITHM_SHA384_GUID + - EFI_HASH_ALGORITHM_SHA512_GUID + @param[in] PaddingMethod Padding method used jointly with hash algorithm, + one of: + - EFI_PADDING_NONE_GUID + - EFI_PADDING_RSAES_PKCS1V1P5_GUID + - EFI_PADDING_RSAES_OAEP_GUID + @param[in] EncryptedSize Size of data to decrypt. + @param[in] EncryptedData Data to decrypt + @param[in, out] PlaintextSize On input, in bytes, the size of buffer to store + the decrypted data. + On output, in bytes, the size of buffer required + to store the decrypted data. + @param[out] PlaintextData Buffer for decrypted data, padding removed. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER KeyId is not valid or associated key not of type + SC_EDGE_RSA_EXCHANGE. + @retval EFI_INVALID_PARAMETER HashAlgorithm is NULL. + @retval EFI_INVALID_PARAMETER HashAlgorithm is not valid. + @retval EFI_INVALID_PARAMETER PaddingMethod is NULL. + @retval EFI_INVALID_PARAMETER PaddingMethod is not valid. + @retval EFI_INVALID_PARAMETER EncryptedSize is 0. + @retval EFI_INVALID_PARAMETER EncryptedData is NULL. + @retval EFI_INVALID_PARAMETER PlaintextSize is NULL. + @retval EFI_INVALID_PARAMETER PlaintextData is NULL. + @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. + PIN not verified. + @retval EFI_BUFFER_TOO_SMALL PlaintextSize is too small for the plaintext data + and the required size is returned in PlaintextSize. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_DECRYPT_DATA) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN UINTN KeyId, + IN EFI_GUID *HashAlgorithm, + IN EFI_GUID *PaddingMethod, + IN UINTN EncryptedSize, + IN UINT8 *EncryptedData, + IN OUT UINTN *PlaintextSize, + OUT UINT8 *PlaintextData + ); + +/** + This function performs a secret Diffie Hellman agreement calculation that would + be used to derive a symmetric encryption / decryption key. + + The function compute a DH agreement that should be diversified togenerate a symmetric + key to proceed encryption or decryption. + + The application and the Smart Card shall agree on the diversification process. + + The KeyId must reference a key of one of the types: SC_EDGE_ECDH_256, SC_EDGE_ECDH_384 + or SC_EDGE_ECDH_521. + + @param[in] This Indicates a pointer to the calling context. + @param[in] SCardHandle Handle on Smart Card connection. + @param[in] KeyId Identifier of the key container, retrieved + in a key index item of credentials. + @param[in] dataQx Public key x coordinate. Size is the same as + key size for KeyId. Stored in big endian format. + @param[in] dataQy Public key y coordinate. Size is the same as + key size for KeyId. Stored in big endian format. + @param[out] DHAgreement Buffer for DH agreement computed. Size must be + bigger or equal to key size for KeyId. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER No connection for SCardHandle value. + @retval EFI_INVALID_PARAMETER KeyId is not valid. + @retval EFI_INVALID_PARAMETER dataQx is NULL. + @retval EFI_INVALID_PARAMETER dataQy is NULL. + @retval EFI_INVALID_PARAMETER DHAgreement is NULL. + @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled. + PIN not verified. + @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection + has been removed. A Disconnect should be performed. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT) ( + IN EFI_SMART_CARD_EDGE_PROTOCOL *This, + IN EFI_HANDLE SCardHandle, + IN UINTN KeyId, + IN UINT8 *dataQx, + IN UINT8 *dataQy, + OUT UINT8 *DHAgreement + ); + +/// +/// Smart card aware application invokes this protocol to get access to an inserted +/// smart card in the reader or to the reader itself. +/// +struct _EFI_SMART_CARD_EDGE_PROTOCOL { + EFI_SMART_CARD_EDGE_GET_CONTEXT GetContext; + EFI_SMART_CARD_EDGE_CONNECT Connect; + EFI_SMART_CARD_EDGE_DISCONNECT Disconnect; + EFI_SMART_CARD_EDGE_GET_CSN GetCsn; + EFI_SMART_CARD_EDGE_GET_READER_NAME GetReaderName; + EFI_SMART_CARD_EDGE_VERIFY_PIN VerifyPin; + EFI_SMART_CARD_EDGE_GET_PIN_REMAINING GetPinRemaining; + EFI_SMART_CARD_EDGE_GET_DATA GetData; + EFI_SMART_CARD_EDGE_GET_CREDENTIAL GetCredential; + EFI_SMART_CARD_EDGE_SIGN_DATA SignData; + EFI_SMART_CARD_EDGE_DECRYPT_DATA DecryptData; + EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT BuildDHAgreement; +}; + +extern EFI_GUID gEfiSmartCardEdgeProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/SmartCardReader.h b/MdePkg/Include/Protocol/SmartCardReader.h index b093774c01..d6e1887db8 100644 --- a/MdePkg/Include/Protocol/SmartCardReader.h +++ b/MdePkg/Include/Protocol/SmartCardReader.h @@ -1,326 +1,326 @@ -/** @file - The UEFI Smart Card Reader Protocol provides an abstraction for device to provide - smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup - specifications and provides an API to applications willing to communicate with a - smart card or a smart card reader. - - Copyright (c) 2015, Intel Corporation. All rights reserved.
- This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef __SMART_CARD_READER_H__ -#define __SMART_CARD_READER_H__ - -#define EFI_SMART_CARD_READER_PROTOCOL_GUID \ - { \ - 0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \ - } - -typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL; - -// -// Codes for access mode -// -#define SCARD_AM_READER 0x0001 // Exclusive access to reader -#define SCARD_AM_CARD 0x0002 // Exclusive access to card -// -// Codes for card action -// -#define SCARD_CA_NORESET 0x0000 // Don't reset card -#define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset -#define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset -#define SCARD_CA_UNPOWER 0x0003 // Power off the card -#define SCARD_CA_EJECT 0x0004 // Eject the card -// -// Protocol types -// -#define SCARD_PROTOCOL_UNDEFINED 0x0000 -#define SCARD_PROTOCOL_T0 0x0001 -#define SCARD_PROTOCOL_T1 0x0002 -#define SCARD_PROTOCOL_RAW 0x0004 -// -// Codes for state type -// -#define SCARD_UNKNOWN 0x0000 /* state is unknown */ -#define SCARD_ABSENT 0x0001 /* Card is absent */ -#define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/ -#define SCARD_ACTIVE 0x0003 /* Card is present and powered */ -// -// Macro to generate a ControlCode & PC/SC part 10 control code -// -#define SCARD_CTL_CODE(code) (0x42000000 + (code)) -#define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400) - -/** - This function requests connection to the smart card or the reader, using the - appropriate reset type and protocol. - - The SCardConnectfunction requests access to the smart card or the reader. Upon - success, it is then possible to call SCardTransmit. - - If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to - SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function - fails with EFI_INVALID_PARAMETER. - - @param[in] This Indicates a pointer to the calling context. - @param[in] AccessMode Codes of access mode. - @param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or - SCARD_CA_WARMRESET. - @param[in] PreferredProtocols Bitmask of acceptable protocols. - @param[out] ActiveProtocol A flag that indicates the active protocol. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL - @retval EFI_INVALID_PARAMETER AccessMode is not valid. - @retval EFI_INVALID_PARAMETER CardAction is not valid. - @retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/ - PreferredProtocols. - @retval EFI_NOT_READY A smart card is inserted but failed to return an ATR. - @retval EFI_UNSUPPORTED PreferredProtocols does not contain an available - protocol to use. - @retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is - no smart card inserted. - @retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall. - @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_READER_CONNECT) ( - IN EFI_SMART_CARD_READER_PROTOCOL *This, - IN UINT32 AccessMode, - IN UINT32 CardAction, - IN UINT32 PreferredProtocols, - OUT UINT32 *ActiveProtocol - ); - -/** - This function releases a connection previously taken by SCardConnect. - - The SCardDisconnect function releases the lock previously taken by SCardConnect. - In case the smart card has been removed before this call, thisfunction - returns EFI_SUCCESS. If there is no previous call to SCardConnect, this - function returns EFI_SUCCESS. - - @param[in] This Indicates a pointer to the calling context. - @param[in] CardAction Codes for card action. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL - @retval EFI_INVALID_PARAMETER CardAction value is unknown. - @retval EFI_UNSUPPORTED Reader does not support Eject card feature - (disconnect was not performed). - @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) ( - IN EFI_SMART_CARD_READER_PROTOCOL *This, - IN UINT32 CardAction - ); - -/** - This function retrieves some basic information about the smart card and reader. - - The SCardStatusfunction retrieves basic reader and card information. - - If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but - does not fill in such variables. - - If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered - as valid. - - @param[in] This Indicates a pointer to the calling context. - @param[out] ReaderName A pointer to a NULL terminated string that will - contain the reader name. - @param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the - maximal size, in bytes,of ReaderName. - On output, the required size, in bytes, for ReaderName. - @param[out] State Current state of the smart card reader. - @param[out] CardProtocol Current protocol used to communicate with the smart card. - @param[out] Atr A pointer to retrieve the ATR of the smart card. - @param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes, - of Atr(usually 33). - On output, the required size, inbytes, for the smart - card ATR. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL - @retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL - @retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL - @retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name. - ReaderNameLength has been updated to the required value. - @retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR. - AtrLength has been updated to the required value. - @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_READER_STATUS) ( - IN EFI_SMART_CARD_READER_PROTOCOL *This, - OUT CHAR16 *ReaderName OPTIONAL, - IN OUT UINTN *ReaderNameLength OPTIONAL, - OUT UINT32 *State OPTIONAL, - OUT UINT32 *CardProtocol OPTIONAL, - OUT UINT8 *Atr OPTIONAL, - IN OUT UINTN *AtrLength OPTIONAL - ); - -/** - This function sends a command to the card or reader and returns its response. - - The protocol to use to communicate with the smart card has been selected through - SCardConnectcall. - - In case RAPDULength indicates a buffer too small to holdthe response APDU, the - function fails with EFI_BUFFER_TOO_SMALL. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. - @param[in] CAPDU A pointer to a byte array thatcontains the Command - APDU to send to the smart card or reader. - @param[in] CAPDULength Command APDU size, in bytes. - @param[out] RAPDU A pointer to a byte array that will contain the - Response APDU. - @param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response - APDU. - On output, the size, in bytes, of the Response APDU. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0. - @retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU. - RAPDULength has been updated to the required value. - @retval EFI_NO_MEDIA There is no card in the reader. - @retval EFI_NOT_READY Card is not powered. - @retval EFI_PROTOCOL_ERROR A protocol error has occurred. - @retval EFI_TIMEOUT The reader did not respond. - @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. - @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) ( - IN EFI_SMART_CARD_READER_PROTOCOL *This, - IN UINT8 *CAPDU, - IN UINTN CAPDULength, - OUT UINT8 *RAPDU, - IN OUT UINTN *RAPDULength -); - ); - -/** - This function provides direct access to the reader. - - This function gives direct control to send commands to the driver or the reader. - The ControlCode to use is vendor dependant; the only standard code defined is - the one to get PC/SC part 10 features. - - InBuffer and Outbuffer may be NULL when ControlCode operation does not require - them. - - @param[in] This Indicates a pointer to the calling context. - @param[in] ControlCode The control code for the operation to perform. - @param[in] InBuffer A pointer to the input parameters. - @param[in] InBufferLength Size, in bytes, of input parameters. - @param[out] OutBuffer A pointer to the output parameters. - @param[in, out] OutBufferLength On input, maximal size, in bytes, to store output - parameters. - On output, the size, in bytes, of output parameters. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but: - InBuffer is NULL or InBufferLenth is NULL or - InBuffer is not NULL but InBufferLenth is less than - expected. - @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL. - @retval EFI_UNSUPPORTED ControlCode is not supported. - @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output - parameters. - OutBufferLength has been updated to the required value. - @retval EFI_NO_MEDIA There is no card in the reader and the control code - specified requires one. - @retval EFI_NOT_READY ControlCode requires a powered card to operate. - @retval EFI_PROTOCOL_ERROR A protocol error has occurred. - @retval EFI_TIMEOUT The reader did not respond. - @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. - @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_READER_CONTROL) ( - IN EFI_SMART_CARD_READER_PROTOCOL *This, - IN UINT32 ControlCode, - IN UINT8 *InBuffer OPTIONAL, - IN UINTN InBufferLength OPTIONAL, - OUT UINT8 *OutBuffer OPTIONAL, - IN OUT UINTN *OutBufferLength OPTIONAL - ); - -/** - This function retrieves a reader or smart card attribute. - - Possibly supported attrib values are listed in "PC/SC specification, Part 3: - Requirements for PC-Connected Interface Devices". - - @param[in] This Indicates a pointer to the calling context. - @param[in] Attrib Identifier for the attribute to retrieve. - @param[out] OutBuffer A pointer to a buffer that will contain - attribute data. - @param[in, out] OutBufferLength On input, maximal size, in bytes, to store - attribute data. - On output, the size, in bytes, of attribute - data. - - @retval EFI_SUCCESS The requested command completed successfully. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0. - @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output - parameters. - OutBufferLength has been updated to the required value. - @retval EFI_UNSUPPORTED Attribis not supported - @retval EFI_NO_MEDIA There is no card in the reader and Attrib value - requires one. - @retval EFI_NOT_READY Attrib requires a powered card to operate. - @retval EFI_PROTOCOL_ERROR A protocol error has occurred. - @retval EFI_TIMEOUT The reader did not respond. - @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) ( - IN EFI_SMART_CARD_READER_PROTOCOL *This, - IN UINT32 Attrib, - OUT UINT8 *OutBuffer, - IN OUT UINTN *OutBufferLength - ); - -/// -/// Smart card aware application invokes this protocol to get access to an inserted -/// smart card in the reader or to the reader itself. -/// -struct _EFI_SMART_CARD_READER_PROTOCOL { - EFI_SMART_CARD_READER_CONNECT SCardConnect; - EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect; - EFI_SMART_CARD_READER_STATUS SCardStatus; - EFI_SMART_CARD_READER_TRANSMIT SCardTransmit; - EFI_SMART_CARD_READER_CONTROL SCardControl; - EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib; -}; - -extern EFI_GUID gEfiSmartCardReaderProtocolGuid; - -#endif - +/** @file + The UEFI Smart Card Reader Protocol provides an abstraction for device to provide + smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup + specifications and provides an API to applications willing to communicate with a + smart card or a smart card reader. + + Copyright (c) 2015, Intel Corporation. All rights reserved.
+ This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef __SMART_CARD_READER_H__ +#define __SMART_CARD_READER_H__ + +#define EFI_SMART_CARD_READER_PROTOCOL_GUID \ + { \ + 0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \ + } + +typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL; + +// +// Codes for access mode +// +#define SCARD_AM_READER 0x0001 // Exclusive access to reader +#define SCARD_AM_CARD 0x0002 // Exclusive access to card +// +// Codes for card action +// +#define SCARD_CA_NORESET 0x0000 // Don't reset card +#define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset +#define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset +#define SCARD_CA_UNPOWER 0x0003 // Power off the card +#define SCARD_CA_EJECT 0x0004 // Eject the card +// +// Protocol types +// +#define SCARD_PROTOCOL_UNDEFINED 0x0000 +#define SCARD_PROTOCOL_T0 0x0001 +#define SCARD_PROTOCOL_T1 0x0002 +#define SCARD_PROTOCOL_RAW 0x0004 +// +// Codes for state type +// +#define SCARD_UNKNOWN 0x0000 /* state is unknown */ +#define SCARD_ABSENT 0x0001 /* Card is absent */ +#define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/ +#define SCARD_ACTIVE 0x0003 /* Card is present and powered */ +// +// Macro to generate a ControlCode & PC/SC part 10 control code +// +#define SCARD_CTL_CODE(code) (0x42000000 + (code)) +#define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400) + +/** + This function requests connection to the smart card or the reader, using the + appropriate reset type and protocol. + + The SCardConnectfunction requests access to the smart card or the reader. Upon + success, it is then possible to call SCardTransmit. + + If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to + SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function + fails with EFI_INVALID_PARAMETER. + + @param[in] This Indicates a pointer to the calling context. + @param[in] AccessMode Codes of access mode. + @param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or + SCARD_CA_WARMRESET. + @param[in] PreferredProtocols Bitmask of acceptable protocols. + @param[out] ActiveProtocol A flag that indicates the active protocol. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL + @retval EFI_INVALID_PARAMETER AccessMode is not valid. + @retval EFI_INVALID_PARAMETER CardAction is not valid. + @retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/ + PreferredProtocols. + @retval EFI_NOT_READY A smart card is inserted but failed to return an ATR. + @retval EFI_UNSUPPORTED PreferredProtocols does not contain an available + protocol to use. + @retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is + no smart card inserted. + @retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall. + @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_READER_CONNECT) ( + IN EFI_SMART_CARD_READER_PROTOCOL *This, + IN UINT32 AccessMode, + IN UINT32 CardAction, + IN UINT32 PreferredProtocols, + OUT UINT32 *ActiveProtocol + ); + +/** + This function releases a connection previously taken by SCardConnect. + + The SCardDisconnect function releases the lock previously taken by SCardConnect. + In case the smart card has been removed before this call, thisfunction + returns EFI_SUCCESS. If there is no previous call to SCardConnect, this + function returns EFI_SUCCESS. + + @param[in] This Indicates a pointer to the calling context. + @param[in] CardAction Codes for card action. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL + @retval EFI_INVALID_PARAMETER CardAction value is unknown. + @retval EFI_UNSUPPORTED Reader does not support Eject card feature + (disconnect was not performed). + @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) ( + IN EFI_SMART_CARD_READER_PROTOCOL *This, + IN UINT32 CardAction + ); + +/** + This function retrieves some basic information about the smart card and reader. + + The SCardStatusfunction retrieves basic reader and card information. + + If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but + does not fill in such variables. + + If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered + as valid. + + @param[in] This Indicates a pointer to the calling context. + @param[out] ReaderName A pointer to a NULL terminated string that will + contain the reader name. + @param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the + maximal size, in bytes,of ReaderName. + On output, the required size, in bytes, for ReaderName. + @param[out] State Current state of the smart card reader. + @param[out] CardProtocol Current protocol used to communicate with the smart card. + @param[out] Atr A pointer to retrieve the ATR of the smart card. + @param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes, + of Atr(usually 33). + On output, the required size, inbytes, for the smart + card ATR. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL + @retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL + @retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL + @retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name. + ReaderNameLength has been updated to the required value. + @retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR. + AtrLength has been updated to the required value. + @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_READER_STATUS) ( + IN EFI_SMART_CARD_READER_PROTOCOL *This, + OUT CHAR16 *ReaderName OPTIONAL, + IN OUT UINTN *ReaderNameLength OPTIONAL, + OUT UINT32 *State OPTIONAL, + OUT UINT32 *CardProtocol OPTIONAL, + OUT UINT8 *Atr OPTIONAL, + IN OUT UINTN *AtrLength OPTIONAL + ); + +/** + This function sends a command to the card or reader and returns its response. + + The protocol to use to communicate with the smart card has been selected through + SCardConnectcall. + + In case RAPDULength indicates a buffer too small to holdthe response APDU, the + function fails with EFI_BUFFER_TOO_SMALL. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. + @param[in] CAPDU A pointer to a byte array thatcontains the Command + APDU to send to the smart card or reader. + @param[in] CAPDULength Command APDU size, in bytes. + @param[out] RAPDU A pointer to a byte array that will contain the + Response APDU. + @param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response + APDU. + On output, the size, in bytes, of the Response APDU. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0. + @retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU. + RAPDULength has been updated to the required value. + @retval EFI_NO_MEDIA There is no card in the reader. + @retval EFI_NOT_READY Card is not powered. + @retval EFI_PROTOCOL_ERROR A protocol error has occurred. + @retval EFI_TIMEOUT The reader did not respond. + @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. + @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) ( + IN EFI_SMART_CARD_READER_PROTOCOL *This, + IN UINT8 *CAPDU, + IN UINTN CAPDULength, + OUT UINT8 *RAPDU, + IN OUT UINTN *RAPDULength +); + ); + +/** + This function provides direct access to the reader. + + This function gives direct control to send commands to the driver or the reader. + The ControlCode to use is vendor dependant; the only standard code defined is + the one to get PC/SC part 10 features. + + InBuffer and Outbuffer may be NULL when ControlCode operation does not require + them. + + @param[in] This Indicates a pointer to the calling context. + @param[in] ControlCode The control code for the operation to perform. + @param[in] InBuffer A pointer to the input parameters. + @param[in] InBufferLength Size, in bytes, of input parameters. + @param[out] OutBuffer A pointer to the output parameters. + @param[in, out] OutBufferLength On input, maximal size, in bytes, to store output + parameters. + On output, the size, in bytes, of output parameters. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but: + InBuffer is NULL or InBufferLenth is NULL or + InBuffer is not NULL but InBufferLenth is less than + expected. + @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL. + @retval EFI_UNSUPPORTED ControlCode is not supported. + @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output + parameters. + OutBufferLength has been updated to the required value. + @retval EFI_NO_MEDIA There is no card in the reader and the control code + specified requires one. + @retval EFI_NOT_READY ControlCode requires a powered card to operate. + @retval EFI_PROTOCOL_ERROR A protocol error has occurred. + @retval EFI_TIMEOUT The reader did not respond. + @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. + @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_READER_CONTROL) ( + IN EFI_SMART_CARD_READER_PROTOCOL *This, + IN UINT32 ControlCode, + IN UINT8 *InBuffer OPTIONAL, + IN UINTN InBufferLength OPTIONAL, + OUT UINT8 *OutBuffer OPTIONAL, + IN OUT UINTN *OutBufferLength OPTIONAL + ); + +/** + This function retrieves a reader or smart card attribute. + + Possibly supported attrib values are listed in "PC/SC specification, Part 3: + Requirements for PC-Connected Interface Devices". + + @param[in] This Indicates a pointer to the calling context. + @param[in] Attrib Identifier for the attribute to retrieve. + @param[out] OutBuffer A pointer to a buffer that will contain + attribute data. + @param[in, out] OutBufferLength On input, maximal size, in bytes, to store + attribute data. + On output, the size, in bytes, of attribute + data. + + @retval EFI_SUCCESS The requested command completed successfully. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0. + @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output + parameters. + OutBufferLength has been updated to the required value. + @retval EFI_UNSUPPORTED Attribis not supported + @retval EFI_NO_MEDIA There is no card in the reader and Attrib value + requires one. + @retval EFI_NOT_READY Attrib requires a powered card to operate. + @retval EFI_PROTOCOL_ERROR A protocol error has occurred. + @retval EFI_TIMEOUT The reader did not respond. + @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) ( + IN EFI_SMART_CARD_READER_PROTOCOL *This, + IN UINT32 Attrib, + OUT UINT8 *OutBuffer, + IN OUT UINTN *OutBufferLength + ); + +/// +/// Smart card aware application invokes this protocol to get access to an inserted +/// smart card in the reader or to the reader itself. +/// +struct _EFI_SMART_CARD_READER_PROTOCOL { + EFI_SMART_CARD_READER_CONNECT SCardConnect; + EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect; + EFI_SMART_CARD_READER_STATUS SCardStatus; + EFI_SMART_CARD_READER_TRANSMIT SCardTransmit; + EFI_SMART_CARD_READER_CONTROL SCardControl; + EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib; +}; + +extern EFI_GUID gEfiSmartCardReaderProtocolGuid; + +#endif + diff --git a/MdePkg/Include/Protocol/UsbFunctionIo.h b/MdePkg/Include/Protocol/UsbFunctionIo.h index 4422567f19..923c1d3527 100644 --- a/MdePkg/Include/Protocol/UsbFunctionIo.h +++ b/MdePkg/Include/Protocol/UsbFunctionIo.h @@ -1,683 +1,683 @@ -/** @file - The USB Function Protocol provides an I/O abstraction for a USB Controller - operating in Function mode (also commonly referred to as Device, Peripheral, - or Target mode) and the mechanisms by which the USB Function can communicate - with the USB Host. It is used by other UEFI drivers or applications to - perform data transactions and basic USB controller management over a USB - Function port. - - This simple protocol only supports USB 2.0 bulk transfers on systems with a - single configuration and a single interface. It does not support isochronous - or interrupt transfers, alternate interfaces, or USB 3.0 functionality. - Future revisions of this protocol may support these or additional features. - - Copyright (c) 2015, Intel Corporation. All rights reserved.
- This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -**/ - -#ifndef __USB_FUNCTION_IO_H__ -#define __USB_FUNCTION_IO_H__ - -#include - -#define EFI_USBFN_IO_PROTOCOL_GUID \ - { \ - 0x32d2963a, 0xfe5d, 0x4f30, {0xb6, 0x33, 0x6e, 0x5d, 0xc5, 0x58, 0x3, 0xcc} \ - } - -typedef struct _EFI_USBFN_IO_PROTOCOL EFI_USBFN_IO_PROTOCOL; - -#define EFI_USBFN_IO_PROTOCOL_REVISION 0x00010001 - -typedef enum _EFI_USBFN_PORT_TYPE { - EfiUsbUnknownPort = 0, - EfiUsbStandardDownstreamPort, - EfiUsbChargingDownstreamPort, - EfiUsbDedicatedChargingPort, - EfiUsbInvalidDedicatedChargingPort -} EFI_USBFN_PORT_TYPE; - -typedef struct { - EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor; - EFI_USB_ENDPOINT_DESCRIPTOR **EndpointDescriptorTable; -} EFI_USB_INTERFACE_INFO; - -typedef struct { - EFI_USB_CONFIG_DESCRIPTOR *ConfigDescriptor; - EFI_USB_INTERFACE_INFO **InterfaceInfoTable; -} EFI_USB_CONFIG_INFO; - -typedef struct { - EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor; - EFI_USB_CONFIG_INFO **ConfigInfoTable; -} EFI_USB_DEVICE_INFO; - -typedef enum _EFI_USB_ENDPOINT_TYPE { - UsbEndpointControl = 0x00, - //UsbEndpointIsochronous = 0x01, - UsbEndpointBulk = 0x02, - //UsbEndpointInterrupt = 0x03 -} EFI_USB_ENDPOINT_TYPE; - -typedef enum _EFI_USBFN_DEVICE_INFO_ID { - EfiUsbDeviceInfoUnknown = 0, - EfiUsbDeviceInfoSerialNumber, - EfiUsbDeviceInfoManufacturerName, - EfiUsbDeviceInfoProductName -} EFI_USBFN_DEVICE_INFO_ID; - -typedef enum _EFI_USBFN_ENDPOINT_DIRECTION { - EfiUsbEndpointDirectionHostOut = 0, - EfiUsbEndpointDirectionHostIn, - EfiUsbEndpointDirectionDeviceTx = EfiUsbEndpointDirectionHostIn, - EfiUsbEndpointDirectionDeviceRx = EfiUsbEndpointDirectionHostOut -} EFI_USBFN_ENDPOINT_DIRECTION; - -typedef enum _EFI_USBFN_MESSAGE { - // - // Nothing - // - EfiUsbMsgNone = 0, - // - // SETUP packet is received, returned Buffer contains - // EFI_USB_DEVICE_REQUEST struct - // - EfiUsbMsgSetupPacket, - // - // Indicates that some of the requested data has been received from the - // host. It is the responsibility of the class driver to determine if it - // needs to wait for any remaining data. Returned Buffer contains - // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer - // status and count of bytes received. - // - EfiUsbMsgEndpointStatusChangedRx, - // - // Indicates that some of the requested data has been transmitted to the - // host. It is the responsibility of the class driver to determine if any - // remaining data needs to be resent. Returned Buffer contains - // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer - // status and count of bytes sent. - // - EfiUsbMsgEndpointStatusChangedTx, - // - // DETACH bus event signaled - // - EfiUsbMsgBusEventDetach, - // - // ATTACH bus event signaled - // - EfiUsbMsgBusEventAttach, - // - // RESET bus event signaled - // - EfiUsbMsgBusEventReset, - // - // SUSPEND bus event signaled - // - EfiUsbMsgBusEventSuspend, - // - // RESUME bus event signaled - // - EfiUsbMsgBusEventResume, - // - // Bus speed updated, returned buffer indicated bus speed using - // following enumeration named EFI_USB_BUS_SPEED - // - EfiUsbMsgBusEventSpeed -} EFI_USBFN_MESSAGE; - -typedef enum _EFI_USBFN_TRANSFER_STATUS { - UsbTransferStatusUnknown = 0, - UsbTransferStatusComplete, - UsbTransferStatusAborted, - UsbTransferStatusActive, - UsbTransferStatusNone -} EFI_USBFN_TRANSFER_STATUS; - -typedef struct _EFI_USBFN_TRANSFER_RESULT { - UINTN BytesTransferred; - EFI_USBFN_TRANSFER_STATUS TransferStatus; - UINT8 EndpointIndex; - EFI_USBFN_ENDPOINT_DIRECTION Direction; - VOID *Buffer; -} EFI_USBFN_TRANSFER_RESULT; - -typedef enum _EFI_USB_BUS_SPEED { - UsbBusSpeedUnknown = 0, - UsbBusSpeedLow, - UsbBusSpeedFull, - UsbBusSpeedHigh, - UsbBusSpeedSuper, - UsbBusSpeedMaximum = UsbBusSpeedSuper -} EFI_USB_BUS_SPEED; - -typedef union _EFI_USBFN_MESSAGE_PAYLOAD { - EFI_USB_DEVICE_REQUEST udr; - EFI_USBFN_TRANSFER_RESULT utr; - EFI_USB_BUS_SPEED ubs; -} EFI_USBFN_MESSAGE_PAYLOAD; - -typedef enum _EFI_USBFN_POLICY_TYPE { - EfiUsbPolicyUndefined = 0, - EfiUsbPolicyMaxTransactionSize, - EfiUsbPolicyZeroLengthTerminationSupport, - EfiUsbPolicyZeroLengthTermination -} EFI_USBFN_POLICY_TYPE; - -/** - Returns information about what USB port type was attached. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[out] PortType Returns the USB port type. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to - process this request or there is no USB port - attached to the device. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_DETECT_PORT) ( - IN EFI_USBFN_IO_PROTOCOL *This, - OUT EFI_USBFN_PORT_TYPE *PortType - ); - -/** - Configures endpoints based on supplied device and configuration descriptors. - - Assuming that the hardware has already been initialized, this function configures - the endpoints using the device information supplied by DeviceInfo, activates the - port, and starts receiving USB events. - - This function must ignore the bMaxPacketSize0field of the Standard Device Descriptor - and the wMaxPacketSize field of the Standard Endpoint Descriptor that are made - available through DeviceInfo. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[out] DeviceInfo A pointer to EFI_USBFN_DEVICE_INFO instance. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - @retval EFI_OUT_OF_RESOURCES The request could not be completed due to lack of - resources. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS) ( - IN EFI_USBFN_IO_PROTOCOL *This, - OUT EFI_USB_DEVICE_INFO *DeviceInfo - ); - -/** - Returns the maximum packet size of the specified endpoint type for the supplied - bus speed. - - If the BusSpeed is UsbBusSpeedUnknown, the maximum speed the underlying controller - supports is assumed. - - This protocol currently does not support isochronous or interrupt transfers. Future - revisions of this protocol may eventually support it. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. - @param[in] EndpointType Endpoint type as defined as EFI_USB_ENDPOINT_TYPE. - @param[in] BusSpeed Bus speed as defined as EFI_USB_BUS_SPEED. - @param[out] MaxPacketSize The maximum packet size, in bytes, of the specified - endpoint type. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN EFI_USB_ENDPOINT_TYPE EndpointType, - IN EFI_USB_BUS_SPEED BusSpeed, - OUT UINT16 *MaxPacketSize - ); - -/** - Returns device specific information based on the supplied identifier as a Unicode string. - - If the supplied Buffer isn't large enough, or is NULL, the method fails with - EFI_BUFFER_TOO_SMALL and the required size is returned through BufferSize. All returned - strings are in Unicode format. - - An Id of EfiUsbDeviceInfoUnknown is treated as an invalid parameter. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. - @param[in] Id The requested information id. - - - @param[in] BufferSize On input, the size of the Buffer in bytes. On output, the - amount of data returned in Buffer in bytes. - @param[out] Buffer A pointer to a buffer to returnthe requested information - as a Unicode string. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_BUFFER_TOO_SMALL Supplied buffer isn't large enough to hold the request string. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_GET_DEVICE_INFO) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN EFI_USBFN_DEVICE_INFO_ID Id, - IN OUT UINTN *BufferSize, - OUT VOID *Buffer OPTIONAL -); - -/** - Returns the vendor-id and product-id of the device. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[out] Vid Returned vendor-id of the device. - @param[out] Pid Returned product-id of the device. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_NOT_FOUND Unable to return the vendor-id or the product-id. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID) ( - IN EFI_USBFN_IO_PROTOCOL *This, - OUT UINT16 *Vid, - OUT UINT16 *Pid -); - -/** - Aborts the transfer on the specified endpoint. - - This function should fail with EFI_INVALID_PARAMETER if the specified direction - is incorrect for the endpoint. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] EndpointIndex Indicates the endpoint on which the ongoing transfer - needs to be canceled. - @param[in] Direction Direction of the endpoint. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_ABORT_TRANSFER) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINT8 EndpointIndex, - IN EFI_USBFN_ENDPOINT_DIRECTION Direction -); - -/** - Returns the stall state on the specified endpoint. - - This function should fail with EFI_INVALID_PARAMETER if the specified direction - is incorrect for the endpoint. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] EndpointIndex Indicates the endpoint. - @param[in] Direction Direction of the endpoint. - @param[in, out] State Boolean, true value indicates that the endpoint - is in a stalled state, false otherwise. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINT8 EndpointIndex, - IN EFI_USBFN_ENDPOINT_DIRECTION Direction, - IN OUT BOOLEAN *State -); - -/** - Sets or clears the stall state on the specified endpoint. - - This function should fail with EFI_INVALID_PARAMETER if the specified direction - is incorrect for the endpoint. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] EndpointIndex Indicates the endpoint. - @param[in] Direction Direction of the endpoint. - @param[in] State Requested stall state on the specified endpoint. - True value causes the endpoint to stall; false - value clears an existing stall. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINT8 EndpointIndex, - IN EFI_USBFN_ENDPOINT_DIRECTION Direction, - IN OUT BOOLEAN *State -); - -/** - This function is called repeatedly to get information on USB bus states, - receive-completion and transmit-completion events on the endpoints, and - notification on setup packet on endpoint 0. - - A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler()repeatedly - to receive updates on the transfer status and number of bytes transferred - on various endpoints. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[out] Message Indicates the event that initiated this notification. - @param[in, out] PayloadSize On input, the size of the memory pointed by - Payload. On output, the amount ofdata returned - in Payload. - @param[out] Payload A pointer to EFI_USBFN_MESSAGE_PAYLOAD instance - to return additional payload for current message. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - @retval EFI_BUFFER_TOO_SMALL The Supplied buffer is not large enough to hold - the message payload. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_EVENTHANDLER) ( - IN EFI_USBFN_IO_PROTOCOL *This, - OUT EFI_USBFN_MESSAGE *Message, - IN OUT UINTN *PayloadSize, - OUT EFI_USBFN_MESSAGE_PAYLOAD *Payload -); - -/** - This function handles transferring data to or from the host on the specified - endpoint, depending on the direction specified. - - A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler() repeatedly to - receive updates on the transfer status and the number of bytes transferred on - various endpoints. Upon an update of the transfer status, the Buffer field of - the EFI_USBFN_TRANSFER_RESULT structure (as described in the function description - for EFI_USBFN_IO_PROTOCOL.EventHandler()) must be initialized with the Buffer - pointer that was supplied to this method. - - The overview of the call sequence is illustrated in the Figure 54. - - This function should fail with EFI_INVALID_PARAMETER if the specified direction - is incorrect for the endpoint. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] EndpointIndex Indicates the endpoint on which TX or RX transfer - needs to take place. - @param[in] Direction Direction of the endpoint. - @param[in, out] BufferSize If Direction is EfiUsbEndpointDirectionDeviceRx: - On input, the size of the Bufferin bytes. - On output, the amount of data returned in Buffer - in bytes. - If Direction is EfiUsbEndpointDirectionDeviceTx: - On input, the size of the Bufferin bytes. - On output, the amount of data transmitted in bytes. - @param[in, out] Buffer If Direction is EfiUsbEndpointDirectionDeviceRx: - The Buffer to return the received data. - If Directionis EfiUsbEndpointDirectionDeviceTx: - The Buffer that contains the data to be transmitted. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_TRANSFER) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINT8 EndpointIndex, - IN EFI_USBFN_ENDPOINT_DIRECTION Direction, - IN OUT UINTN *BufferSize, - IN OUT VOID *Buffer -); - -/** - Returns the maximum supported transfer size. - - Returns the maximum number of bytes that the underlying controller can accommodate - in a single transfer. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[out] MaxTransferSize The maximum supported transfer size, in bytes. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_NOT_READY The physical device is busy or not ready to process - this request. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_GET_MAXTRANSFER_SIZE) ( - IN EFI_USBFN_IO_PROTOCOL *This, - OUT UINTN *MaxTransferSize - ); - -/** - Allocates a transfer buffer of the specified sizethat satisfies the controller - requirements. - - The AllocateTransferBuffer() function allocates a memory region of Size bytes and - returns the address of the allocated memory that satisfies the underlying controller - requirements in the location referenced by Buffer. - - The allocated transfer buffer must be freed using a matching call to - EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer()function. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] Size The number of bytes to allocate for the transfer buffer. - @param[out] Buffer A pointer to a pointer to the allocated buffer if the - call succeeds; undefined otherwise. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_OUT_OF_RESOURCES The requested transfer buffer could not be allocated. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINTN Size, - OUT VOID **Buffer - ); - -/** - Deallocates the memory allocated for the transfer buffer by the - EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer() function. - - The EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer() function deallocates the - memory specified by Buffer. The Buffer that is freed must have been allocated - by EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer(). - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] Buffer A pointer to the transfer buffer to deallocate. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_FREE_TRANSFER_BUFFER) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN VOID *Buffer - ); - -/** - This function supplies power to the USB controller if needed and initializes - the hardware and the internal data structures. The port must not be activated - by this function. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_START_CONTROLLER) ( - IN EFI_USBFN_IO_PROTOCOL *This - ); - -/** - This function stops the USB hardware device. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_STOP_CONTROLLER) ( - IN EFI_USBFN_IO_PROTOCOL *This - ); - -/** - This function sets the configuration policy for the specified non-control - endpoint. - - This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController() - or after EFI_USBFN_IO_PROTOCOL.StopController() has been called. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] EndpointIndex Indicates the non-control endpoint for which the - policy needs to be set. - @param[in] Direction Direction of the endpoint. - @param[in] PolicyType Policy type the user is trying to set for the - specified non-control endpoint. - @param[in] BufferSize The size of the Bufferin bytes. - @param[in] Buffer The new value for the policy parameter that - PolicyType specifies. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The physical device reported an error. - @retval EFI_UNSUPPORTED Changing this policy value is not supported. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_POLICY) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINT8 EndpointIndex, - IN EFI_USBFN_ENDPOINT_DIRECTION Direction, - IN EFI_USBFN_POLICY_TYPE PolicyType, - IN UINTN BufferSize, - IN VOID *Buffer - ); - -/** - This function sets the configuration policy for the specified non-control - endpoint. - - This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController() - or after EFI_USBFN_IO_PROTOCOL.StopController() has been called. - - @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. - @param[in] EndpointIndex Indicates the non-control endpoint for which the - policy needs to be set. - @param[in] Direction Direction of the endpoint. - @param[in] PolicyType Policy type the user is trying to retrieve for - the specified non-control endpoint. - @param[in, out] BufferSize On input, the size of Bufferin bytes. On output, - the amount of data returned in Bufferin bytes. - @param[in, out] Buffer A pointer to a buffer to return requested endpoint - policy value. - - @retval EFI_SUCCESS The function returned successfully. - @retval EFI_INVALID_PARAMETER A parameter is invalid. - @retval EFI_DEVICE_ERROR The specified policy value is not supported. - @retval EFI_BUFFER_TOO_SMALL Supplied buffer is not large enough to hold requested - policy value. - -**/ -typedef -EFI_STATUS -(EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_POLICY) ( - IN EFI_USBFN_IO_PROTOCOL *This, - IN UINT8 EndpointIndex, - IN EFI_USBFN_ENDPOINT_DIRECTION Direction, - IN EFI_USBFN_POLICY_TYPE PolicyType, - IN OUT UINTN *BufferSize, - IN OUT VOID *Buffer - ); - -/// -/// The EFI_USBFN_IO_PROTOCOL provides basic data transactions and basic USB -/// controller management for a USB Function port. -/// -struct _EFI_USBFN_IO_PROTOCOL { - UINT32 Revision; - EFI_USBFN_IO_DETECT_PORT DetectPort; - EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS ConfigureEnableEndpoints; - EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE GetEndpointMaxPacketSize; - EFI_USBFN_IO_GET_DEVICE_INFO GetDeviceInfo; - EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID GetVendorIdProductId; - EFI_USBFN_IO_ABORT_TRANSFER AbortTransfer; - EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE GetEndpointStallState; - EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE SetEndpointStallState; - EFI_USBFN_IO_EVENTHANDLER EventHandler; - EFI_USBFN_IO_TRANSFER Transfer; - EFI_USBFN_IO_GET_MAXTRANSFER_SIZE GetMaxTransferSize; - EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER AllocateTransferBuffer; - EFI_USBFN_IO_FREE_TRANSFER_BUFFER FreeTransferBuffer; - EFI_USBFN_IO_START_CONTROLLER StartController; - EFI_USBFN_IO_STOP_CONTROLLER StopController; - EFI_USBFN_IO_SET_ENDPOINT_POLICY SetEndpointPolicy; - EFI_USBFN_IO_GET_ENDPOINT_POLICY GetEndpointPolicy; -}; - -extern EFI_GUID gEfiUsbFunctionIoProtocolGuid; - -#endif - +/** @file + The USB Function Protocol provides an I/O abstraction for a USB Controller + operating in Function mode (also commonly referred to as Device, Peripheral, + or Target mode) and the mechanisms by which the USB Function can communicate + with the USB Host. It is used by other UEFI drivers or applications to + perform data transactions and basic USB controller management over a USB + Function port. + + This simple protocol only supports USB 2.0 bulk transfers on systems with a + single configuration and a single interface. It does not support isochronous + or interrupt transfers, alternate interfaces, or USB 3.0 functionality. + Future revisions of this protocol may support these or additional features. + + Copyright (c) 2015, Intel Corporation. All rights reserved.
+ This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef __USB_FUNCTION_IO_H__ +#define __USB_FUNCTION_IO_H__ + +#include + +#define EFI_USBFN_IO_PROTOCOL_GUID \ + { \ + 0x32d2963a, 0xfe5d, 0x4f30, {0xb6, 0x33, 0x6e, 0x5d, 0xc5, 0x58, 0x3, 0xcc} \ + } + +typedef struct _EFI_USBFN_IO_PROTOCOL EFI_USBFN_IO_PROTOCOL; + +#define EFI_USBFN_IO_PROTOCOL_REVISION 0x00010001 + +typedef enum _EFI_USBFN_PORT_TYPE { + EfiUsbUnknownPort = 0, + EfiUsbStandardDownstreamPort, + EfiUsbChargingDownstreamPort, + EfiUsbDedicatedChargingPort, + EfiUsbInvalidDedicatedChargingPort +} EFI_USBFN_PORT_TYPE; + +typedef struct { + EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor; + EFI_USB_ENDPOINT_DESCRIPTOR **EndpointDescriptorTable; +} EFI_USB_INTERFACE_INFO; + +typedef struct { + EFI_USB_CONFIG_DESCRIPTOR *ConfigDescriptor; + EFI_USB_INTERFACE_INFO **InterfaceInfoTable; +} EFI_USB_CONFIG_INFO; + +typedef struct { + EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor; + EFI_USB_CONFIG_INFO **ConfigInfoTable; +} EFI_USB_DEVICE_INFO; + +typedef enum _EFI_USB_ENDPOINT_TYPE { + UsbEndpointControl = 0x00, + //UsbEndpointIsochronous = 0x01, + UsbEndpointBulk = 0x02, + //UsbEndpointInterrupt = 0x03 +} EFI_USB_ENDPOINT_TYPE; + +typedef enum _EFI_USBFN_DEVICE_INFO_ID { + EfiUsbDeviceInfoUnknown = 0, + EfiUsbDeviceInfoSerialNumber, + EfiUsbDeviceInfoManufacturerName, + EfiUsbDeviceInfoProductName +} EFI_USBFN_DEVICE_INFO_ID; + +typedef enum _EFI_USBFN_ENDPOINT_DIRECTION { + EfiUsbEndpointDirectionHostOut = 0, + EfiUsbEndpointDirectionHostIn, + EfiUsbEndpointDirectionDeviceTx = EfiUsbEndpointDirectionHostIn, + EfiUsbEndpointDirectionDeviceRx = EfiUsbEndpointDirectionHostOut +} EFI_USBFN_ENDPOINT_DIRECTION; + +typedef enum _EFI_USBFN_MESSAGE { + // + // Nothing + // + EfiUsbMsgNone = 0, + // + // SETUP packet is received, returned Buffer contains + // EFI_USB_DEVICE_REQUEST struct + // + EfiUsbMsgSetupPacket, + // + // Indicates that some of the requested data has been received from the + // host. It is the responsibility of the class driver to determine if it + // needs to wait for any remaining data. Returned Buffer contains + // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer + // status and count of bytes received. + // + EfiUsbMsgEndpointStatusChangedRx, + // + // Indicates that some of the requested data has been transmitted to the + // host. It is the responsibility of the class driver to determine if any + // remaining data needs to be resent. Returned Buffer contains + // EFI_USBFN_TRANSFER_RESULT struct containing endpoint number, transfer + // status and count of bytes sent. + // + EfiUsbMsgEndpointStatusChangedTx, + // + // DETACH bus event signaled + // + EfiUsbMsgBusEventDetach, + // + // ATTACH bus event signaled + // + EfiUsbMsgBusEventAttach, + // + // RESET bus event signaled + // + EfiUsbMsgBusEventReset, + // + // SUSPEND bus event signaled + // + EfiUsbMsgBusEventSuspend, + // + // RESUME bus event signaled + // + EfiUsbMsgBusEventResume, + // + // Bus speed updated, returned buffer indicated bus speed using + // following enumeration named EFI_USB_BUS_SPEED + // + EfiUsbMsgBusEventSpeed +} EFI_USBFN_MESSAGE; + +typedef enum _EFI_USBFN_TRANSFER_STATUS { + UsbTransferStatusUnknown = 0, + UsbTransferStatusComplete, + UsbTransferStatusAborted, + UsbTransferStatusActive, + UsbTransferStatusNone +} EFI_USBFN_TRANSFER_STATUS; + +typedef struct _EFI_USBFN_TRANSFER_RESULT { + UINTN BytesTransferred; + EFI_USBFN_TRANSFER_STATUS TransferStatus; + UINT8 EndpointIndex; + EFI_USBFN_ENDPOINT_DIRECTION Direction; + VOID *Buffer; +} EFI_USBFN_TRANSFER_RESULT; + +typedef enum _EFI_USB_BUS_SPEED { + UsbBusSpeedUnknown = 0, + UsbBusSpeedLow, + UsbBusSpeedFull, + UsbBusSpeedHigh, + UsbBusSpeedSuper, + UsbBusSpeedMaximum = UsbBusSpeedSuper +} EFI_USB_BUS_SPEED; + +typedef union _EFI_USBFN_MESSAGE_PAYLOAD { + EFI_USB_DEVICE_REQUEST udr; + EFI_USBFN_TRANSFER_RESULT utr; + EFI_USB_BUS_SPEED ubs; +} EFI_USBFN_MESSAGE_PAYLOAD; + +typedef enum _EFI_USBFN_POLICY_TYPE { + EfiUsbPolicyUndefined = 0, + EfiUsbPolicyMaxTransactionSize, + EfiUsbPolicyZeroLengthTerminationSupport, + EfiUsbPolicyZeroLengthTermination +} EFI_USBFN_POLICY_TYPE; + +/** + Returns information about what USB port type was attached. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[out] PortType Returns the USB port type. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to + process this request or there is no USB port + attached to the device. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_DETECT_PORT) ( + IN EFI_USBFN_IO_PROTOCOL *This, + OUT EFI_USBFN_PORT_TYPE *PortType + ); + +/** + Configures endpoints based on supplied device and configuration descriptors. + + Assuming that the hardware has already been initialized, this function configures + the endpoints using the device information supplied by DeviceInfo, activates the + port, and starts receiving USB events. + + This function must ignore the bMaxPacketSize0field of the Standard Device Descriptor + and the wMaxPacketSize field of the Standard Endpoint Descriptor that are made + available through DeviceInfo. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[out] DeviceInfo A pointer to EFI_USBFN_DEVICE_INFO instance. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + @retval EFI_OUT_OF_RESOURCES The request could not be completed due to lack of + resources. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS) ( + IN EFI_USBFN_IO_PROTOCOL *This, + OUT EFI_USB_DEVICE_INFO *DeviceInfo + ); + +/** + Returns the maximum packet size of the specified endpoint type for the supplied + bus speed. + + If the BusSpeed is UsbBusSpeedUnknown, the maximum speed the underlying controller + supports is assumed. + + This protocol currently does not support isochronous or interrupt transfers. Future + revisions of this protocol may eventually support it. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. + @param[in] EndpointType Endpoint type as defined as EFI_USB_ENDPOINT_TYPE. + @param[in] BusSpeed Bus speed as defined as EFI_USB_BUS_SPEED. + @param[out] MaxPacketSize The maximum packet size, in bytes, of the specified + endpoint type. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN EFI_USB_ENDPOINT_TYPE EndpointType, + IN EFI_USB_BUS_SPEED BusSpeed, + OUT UINT16 *MaxPacketSize + ); + +/** + Returns device specific information based on the supplied identifier as a Unicode string. + + If the supplied Buffer isn't large enough, or is NULL, the method fails with + EFI_BUFFER_TOO_SMALL and the required size is returned through BufferSize. All returned + strings are in Unicode format. + + An Id of EfiUsbDeviceInfoUnknown is treated as an invalid parameter. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. + @param[in] Id The requested information id. + + + @param[in] BufferSize On input, the size of the Buffer in bytes. On output, the + amount of data returned in Buffer in bytes. + @param[out] Buffer A pointer to a buffer to returnthe requested information + as a Unicode string. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_BUFFER_TOO_SMALL Supplied buffer isn't large enough to hold the request string. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_GET_DEVICE_INFO) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN EFI_USBFN_DEVICE_INFO_ID Id, + IN OUT UINTN *BufferSize, + OUT VOID *Buffer OPTIONAL +); + +/** + Returns the vendor-id and product-id of the device. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[out] Vid Returned vendor-id of the device. + @param[out] Pid Returned product-id of the device. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_NOT_FOUND Unable to return the vendor-id or the product-id. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID) ( + IN EFI_USBFN_IO_PROTOCOL *This, + OUT UINT16 *Vid, + OUT UINT16 *Pid +); + +/** + Aborts the transfer on the specified endpoint. + + This function should fail with EFI_INVALID_PARAMETER if the specified direction + is incorrect for the endpoint. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] EndpointIndex Indicates the endpoint on which the ongoing transfer + needs to be canceled. + @param[in] Direction Direction of the endpoint. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_ABORT_TRANSFER) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + IN EFI_USBFN_ENDPOINT_DIRECTION Direction +); + +/** + Returns the stall state on the specified endpoint. + + This function should fail with EFI_INVALID_PARAMETER if the specified direction + is incorrect for the endpoint. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] EndpointIndex Indicates the endpoint. + @param[in] Direction Direction of the endpoint. + @param[in, out] State Boolean, true value indicates that the endpoint + is in a stalled state, false otherwise. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + IN EFI_USBFN_ENDPOINT_DIRECTION Direction, + IN OUT BOOLEAN *State +); + +/** + Sets or clears the stall state on the specified endpoint. + + This function should fail with EFI_INVALID_PARAMETER if the specified direction + is incorrect for the endpoint. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] EndpointIndex Indicates the endpoint. + @param[in] Direction Direction of the endpoint. + @param[in] State Requested stall state on the specified endpoint. + True value causes the endpoint to stall; false + value clears an existing stall. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + IN EFI_USBFN_ENDPOINT_DIRECTION Direction, + IN OUT BOOLEAN *State +); + +/** + This function is called repeatedly to get information on USB bus states, + receive-completion and transmit-completion events on the endpoints, and + notification on setup packet on endpoint 0. + + A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler()repeatedly + to receive updates on the transfer status and number of bytes transferred + on various endpoints. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[out] Message Indicates the event that initiated this notification. + @param[in, out] PayloadSize On input, the size of the memory pointed by + Payload. On output, the amount ofdata returned + in Payload. + @param[out] Payload A pointer to EFI_USBFN_MESSAGE_PAYLOAD instance + to return additional payload for current message. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + @retval EFI_BUFFER_TOO_SMALL The Supplied buffer is not large enough to hold + the message payload. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_EVENTHANDLER) ( + IN EFI_USBFN_IO_PROTOCOL *This, + OUT EFI_USBFN_MESSAGE *Message, + IN OUT UINTN *PayloadSize, + OUT EFI_USBFN_MESSAGE_PAYLOAD *Payload +); + +/** + This function handles transferring data to or from the host on the specified + endpoint, depending on the direction specified. + + A class driver must call EFI_USBFN_IO_PROTOCOL.EventHandler() repeatedly to + receive updates on the transfer status and the number of bytes transferred on + various endpoints. Upon an update of the transfer status, the Buffer field of + the EFI_USBFN_TRANSFER_RESULT structure (as described in the function description + for EFI_USBFN_IO_PROTOCOL.EventHandler()) must be initialized with the Buffer + pointer that was supplied to this method. + + The overview of the call sequence is illustrated in the Figure 54. + + This function should fail with EFI_INVALID_PARAMETER if the specified direction + is incorrect for the endpoint. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] EndpointIndex Indicates the endpoint on which TX or RX transfer + needs to take place. + @param[in] Direction Direction of the endpoint. + @param[in, out] BufferSize If Direction is EfiUsbEndpointDirectionDeviceRx: + On input, the size of the Bufferin bytes. + On output, the amount of data returned in Buffer + in bytes. + If Direction is EfiUsbEndpointDirectionDeviceTx: + On input, the size of the Bufferin bytes. + On output, the amount of data transmitted in bytes. + @param[in, out] Buffer If Direction is EfiUsbEndpointDirectionDeviceRx: + The Buffer to return the received data. + If Directionis EfiUsbEndpointDirectionDeviceTx: + The Buffer that contains the data to be transmitted. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_TRANSFER) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + IN EFI_USBFN_ENDPOINT_DIRECTION Direction, + IN OUT UINTN *BufferSize, + IN OUT VOID *Buffer +); + +/** + Returns the maximum supported transfer size. + + Returns the maximum number of bytes that the underlying controller can accommodate + in a single transfer. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[out] MaxTransferSize The maximum supported transfer size, in bytes. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_NOT_READY The physical device is busy or not ready to process + this request. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_GET_MAXTRANSFER_SIZE) ( + IN EFI_USBFN_IO_PROTOCOL *This, + OUT UINTN *MaxTransferSize + ); + +/** + Allocates a transfer buffer of the specified sizethat satisfies the controller + requirements. + + The AllocateTransferBuffer() function allocates a memory region of Size bytes and + returns the address of the allocated memory that satisfies the underlying controller + requirements in the location referenced by Buffer. + + The allocated transfer buffer must be freed using a matching call to + EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer()function. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] Size The number of bytes to allocate for the transfer buffer. + @param[out] Buffer A pointer to a pointer to the allocated buffer if the + call succeeds; undefined otherwise. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_OUT_OF_RESOURCES The requested transfer buffer could not be allocated. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINTN Size, + OUT VOID **Buffer + ); + +/** + Deallocates the memory allocated for the transfer buffer by the + EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer() function. + + The EFI_USBFN_IO_PROTOCOL.FreeTransferBuffer() function deallocates the + memory specified by Buffer. The Buffer that is freed must have been allocated + by EFI_USBFN_IO_PROTOCOL.AllocateTransferBuffer(). + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] Buffer A pointer to the transfer buffer to deallocate. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_FREE_TRANSFER_BUFFER) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN VOID *Buffer + ); + +/** + This function supplies power to the USB controller if needed and initializes + the hardware and the internal data structures. The port must not be activated + by this function. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_START_CONTROLLER) ( + IN EFI_USBFN_IO_PROTOCOL *This + ); + +/** + This function stops the USB hardware device. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_STOP_CONTROLLER) ( + IN EFI_USBFN_IO_PROTOCOL *This + ); + +/** + This function sets the configuration policy for the specified non-control + endpoint. + + This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController() + or after EFI_USBFN_IO_PROTOCOL.StopController() has been called. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] EndpointIndex Indicates the non-control endpoint for which the + policy needs to be set. + @param[in] Direction Direction of the endpoint. + @param[in] PolicyType Policy type the user is trying to set for the + specified non-control endpoint. + @param[in] BufferSize The size of the Bufferin bytes. + @param[in] Buffer The new value for the policy parameter that + PolicyType specifies. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The physical device reported an error. + @retval EFI_UNSUPPORTED Changing this policy value is not supported. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_SET_ENDPOINT_POLICY) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + IN EFI_USBFN_ENDPOINT_DIRECTION Direction, + IN EFI_USBFN_POLICY_TYPE PolicyType, + IN UINTN BufferSize, + IN VOID *Buffer + ); + +/** + This function sets the configuration policy for the specified non-control + endpoint. + + This function can only be called before EFI_USBFN_IO_PROTOCOL.StartController() + or after EFI_USBFN_IO_PROTOCOL.StopController() has been called. + + @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOL instance. + @param[in] EndpointIndex Indicates the non-control endpoint for which the + policy needs to be set. + @param[in] Direction Direction of the endpoint. + @param[in] PolicyType Policy type the user is trying to retrieve for + the specified non-control endpoint. + @param[in, out] BufferSize On input, the size of Bufferin bytes. On output, + the amount of data returned in Bufferin bytes. + @param[in, out] Buffer A pointer to a buffer to return requested endpoint + policy value. + + @retval EFI_SUCCESS The function returned successfully. + @retval EFI_INVALID_PARAMETER A parameter is invalid. + @retval EFI_DEVICE_ERROR The specified policy value is not supported. + @retval EFI_BUFFER_TOO_SMALL Supplied buffer is not large enough to hold requested + policy value. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_USBFN_IO_GET_ENDPOINT_POLICY) ( + IN EFI_USBFN_IO_PROTOCOL *This, + IN UINT8 EndpointIndex, + IN EFI_USBFN_ENDPOINT_DIRECTION Direction, + IN EFI_USBFN_POLICY_TYPE PolicyType, + IN OUT UINTN *BufferSize, + IN OUT VOID *Buffer + ); + +/// +/// The EFI_USBFN_IO_PROTOCOL provides basic data transactions and basic USB +/// controller management for a USB Function port. +/// +struct _EFI_USBFN_IO_PROTOCOL { + UINT32 Revision; + EFI_USBFN_IO_DETECT_PORT DetectPort; + EFI_USBFN_IO_CONFIGURE_ENABLE_ENDPOINTS ConfigureEnableEndpoints; + EFI_USBFN_IO_GET_ENDPOINT_MAXPACKET_SIZE GetEndpointMaxPacketSize; + EFI_USBFN_IO_GET_DEVICE_INFO GetDeviceInfo; + EFI_USBFN_IO_GET_VENDOR_ID_PRODUCT_ID GetVendorIdProductId; + EFI_USBFN_IO_ABORT_TRANSFER AbortTransfer; + EFI_USBFN_IO_GET_ENDPOINT_STALL_STATE GetEndpointStallState; + EFI_USBFN_IO_SET_ENDPOINT_STALL_STATE SetEndpointStallState; + EFI_USBFN_IO_EVENTHANDLER EventHandler; + EFI_USBFN_IO_TRANSFER Transfer; + EFI_USBFN_IO_GET_MAXTRANSFER_SIZE GetMaxTransferSize; + EFI_USBFN_IO_ALLOCATE_TRANSFER_BUFFER AllocateTransferBuffer; + EFI_USBFN_IO_FREE_TRANSFER_BUFFER FreeTransferBuffer; + EFI_USBFN_IO_START_CONTROLLER StartController; + EFI_USBFN_IO_STOP_CONTROLLER StopController; + EFI_USBFN_IO_SET_ENDPOINT_POLICY SetEndpointPolicy; + EFI_USBFN_IO_GET_ENDPOINT_POLICY GetEndpointPolicy; +}; + +extern EFI_GUID gEfiUsbFunctionIoProtocolGuid; + +#endif + -- 2.39.2