diff options
| author | Feng Tian <feng.tian@intel.com> | 2015-05-13 08:35:55 +0000 |
|---|---|---|
| committer | erictian <erictian@Edk2> | 2015-05-13 08:35:55 +0000 |
| commit | 21bd495843a022beb50dc93210c51cf9586553c9 (patch) | |
| tree | 12ceb670432f585bb5739a79482e2f0a1db4b9df /MdePkg/Include | |
| parent | 87bfeb11f84dd1d369bb2e195ef83d20b0d80d61 (diff) | |
| download | edk2-21bd495843a022beb50dc93210c51cf9586553c9.tar.gz edk2-21bd495843a022beb50dc93210c51cf9586553c9.tar.bz2 edk2-21bd495843a022beb50dc93210c51cf9586553c9.zip | |
MdePkg: Fix EOL to be DOS format.
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Feng Tian <feng.tian@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@17429 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdePkg/Include')
| -rw-r--r-- | MdePkg/Include/Protocol/BlockIoCrypto.h | 1060 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/NvmExpressPassthru.h | 572 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/SmartCardEdge.h | 1478 | ||||
| -rw-r--r-- | MdePkg/Include/Protocol/SmartCardReader.h | 652 | ||||
| -rw-r--r-- | 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.<BR> - 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 <Protocol/BlockIo.h> - -#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.<BR>
+ 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 <Protocol/BlockIo.h>
+
+#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.<BR> - 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.<BR>
+ 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.<BR> - 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.<BR>
+ 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.<BR> - 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.<BR>
+ 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.<BR> - 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 <Protocol/UsbIo.h> - -#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.<BR>
+ 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 <Protocol/UsbIo.h>
+
+#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
+
|