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