hsw-nbt 1.2.0
OPTIGA Authenticate NBT Host Library for C
Data Fields | Related Symbols
ifx_protocol_t Struct Reference

Generic protocol struct for building ISO/OSI layer stack. More...

#include <infineon/ifx-protocol.h>

Data Fields

ifx_protocol_t * _base
 Private base layer in ISO/OSI stack.
 
uint64_t _layer_id
 Private layer identification to verify that correct protocol layer called member functions.
 
ifx_protocol_activate_callback_t _activate
 Private protocol activation function for negotiating protocol specific parameters.
 
ifx_protocol_transceive_callback_t _transceive
 Private function for sending and receiving data at once.
 
ifx_protocol_transmit_callback_t _transmit
 Private function for sending data.
 
ifx_protocol_receive_callback_t _receive
 Private function for receiving data.
 
ifx_protocol_destroy_callback_t _destructor
 Private destructor if further cleanup is necessary.
 
ifx_logger_t * _logger
 Private member for optional Logger.
 
void * _properties
 Private member for generic properties as void*.
 

Related Symbols

(Note that these are not member symbols.)

ifx_status_t ifx_apdu_protocol_transceive (ifx_protocol_t *self, const ifx_apdu_t *apdu, ifx_apdu_response_t *response)
 Sends APDU to secure element reads back APDU response.
 
ifx_status_t ifx_i2c_get_clock_frequency (ifx_protocol_t *self, uint32_t *frequency_hz_buffer)
 Getter for I2C clock frequency in [Hz].
 
ifx_status_t ifx_i2c_set_clock_frequency (ifx_protocol_t *self, uint32_t frequency_hz)
 Sets I2C clock frequency in [Hz].
 
ifx_status_t ifx_i2c_get_slave_address (ifx_protocol_t *self, uint16_t *address_buffer)
 Getter for I2C slave address.
 
ifx_status_t ifx_i2c_set_slave_address (ifx_protocol_t *self, uint16_t address)
 Sets I2C slave address.
 
ifx_status_t ifx_i2c_get_guard_time (ifx_protocol_t *self, uint32_t *guard_time_us_buffer)
 Getter for I2C guard time in [us].
 
ifx_status_t ifx_i2c_set_guard_time (ifx_protocol_t *self, uint32_t guard_time_us)
 Sets guard time to be waited between I2C transmissions.
 
ifx_status_t ifx_protocol_activate (ifx_protocol_t *self, uint8_t **response, size_t *response_len)
 Activates secure element and performs protocol negotiation.
 
ifx_status_t ifx_protocol_transceive (ifx_protocol_t *self, const uint8_t *data, size_t data_len, uint8_t **response, size_t *response_len)
 Sends data via Protocol and reads back response.
 
void ifx_protocol_destroy (ifx_protocol_t *self)
 Frees memory associated with Protocol object (but not object itself).
 
void ifx_protocol_set_logger (ifx_protocol_t *self, ifx_logger_t *logger)
 Sets Logger to be used by Protocol.
 
ifx_status_t ifx_t1prime_initialize (ifx_protocol_t *self, ifx_protocol_t *driver)
 Initializes Protocol object for Global Platform T=1' protocol.
 
ifx_status_t ifx_t1prime_set_ifsd (ifx_protocol_t *self, size_t ifsd)
 Sets maximum information field size of the host device (IFSD).
 
ifx_status_t ifx_t1prime_get_bwt (ifx_protocol_t *self, uint16_t *bwt_ms_buffer)
 Returns current block waiting time (BWT) in [ms].
 
ifx_status_t ifx_t1prime_set_bwt (ifx_protocol_t *self, uint16_t bwt_ms)
 Sets block waiting time (BWT) in [ms].
 
ifx_status_t ifx_t1prime_set_irq_handler (ifx_protocol_t *self, ifx_t1prime_irq_handler_t irq)
 Sets T=1' interrupt handler function.
 
ifx_status_t ifx_t1prime_get_irq_handler (ifx_protocol_t *self, ifx_t1prime_irq_handler_t *irq_buffer)
 Getter for T=1' interrupt handler function.
 

Detailed Description

Generic protocol struct for building ISO/OSI layer stack.

Definition at line 226 of file ifx-protocol.h.

Friends And Related Symbol Documentation

◆ ifx_apdu_protocol_transceive()

ifx_status_t ifx_apdu_protocol_transceive ( ifx_protocol_t * self,
const ifx_apdu_t * apdu,
ifx_apdu_response_t * response )
related

Sends APDU to secure element reads back APDU response.

Encodes APDU, then sends it through ISO/OSI protocol. Reads back response and stores it in APDU response.

Parameters
[in]selfProtocol stack for performing necessary operations.
[in]apduAPDU to be send to secure element.
[out]responseBuffer to store response information in.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_i2c_get_clock_frequency()

ifx_status_t ifx_i2c_get_clock_frequency ( ifx_protocol_t * self,
uint32_t * frequency_hz_buffer )
related

Getter for I2C clock frequency in [Hz].

Parameters
[in]selfProtocol object to get clock frequency for.
[out]frequency_hz_bufferBuffer to store clock frequency in.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_i2c_get_guard_time()

ifx_status_t ifx_i2c_get_guard_time ( ifx_protocol_t * self,
uint32_t * guard_time_us_buffer )
related

Getter for I2C guard time in [us].

Some peripherals have a guard time that needs to be waited between consecutive I2C requests. Setting this guard time will ensure that said time is awaited between requests.

Parameters
[in]selfProtocol object to get I2C guard time for.
[out]guard_time_us_bufferBuffer to store I2C guard time in.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_i2c_get_slave_address()

ifx_status_t ifx_i2c_get_slave_address ( ifx_protocol_t * self,
uint16_t * address_buffer )
related

Getter for I2C slave address.

Parameters
[in]selfProtocol object to get I2C slave address for.
[out]address_bufferBuffer to store I2C address in.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_i2c_set_clock_frequency()

ifx_status_t ifx_i2c_set_clock_frequency ( ifx_protocol_t * self,
uint32_t frequency_hz )
related

Sets I2C clock frequency in [Hz].

Parameters
[in]selfProtocol object to set clock frequency for.
[in]frequency_hzDesired clock frequency in [Hz].
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_i2c_set_guard_time()

ifx_status_t ifx_i2c_set_guard_time ( ifx_protocol_t * self,
uint32_t guard_time_us )
related

Sets guard time to be waited between I2C transmissions.

Parameters
[in]selfProtocol object to set I2C guard time for.
[in]guard_time_usDesired I2C guard time in [us].
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.
See also
ifx_i2c_get_guard_time()

◆ ifx_i2c_set_slave_address()

ifx_status_t ifx_i2c_set_slave_address ( ifx_protocol_t * self,
uint16_t address )
related

Sets I2C slave address.

Parameters
[in]selfProtocol object to set I2C slave address for.
[out]addressDesired I2C slave address.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_protocol_activate()

ifx_status_t ifx_protocol_activate ( ifx_protocol_t * self,
uint8_t ** response,
size_t * response_len )
related

Activates secure element and performs protocol negotiation.

Depending on the protocol, data needs to be exchanged with a secure element to negotiate certain protocol aspects like frame sizes, waiting times, etc. This function will perform the initial parameter negotiation.

Parameters
[in]selfProtocol stack for performing necessary operations.
[out]responseBuffer to store response in (e.g. ATR, ATPO, ...).
[out]response_lenBuffer to store number of received bytes in (number of bytes in response).
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_protocol_destroy()

void ifx_protocol_destroy ( ifx_protocol_t * self)
related

Frees memory associated with Protocol object (but not object itself).

Protocol objects can consist of several layers each of which might hold dynamically allocated data that needs special clean-up functionality. Users would need to manually check which members need special care and free them themselves. Calling this function will ensure that all members have been freed properly.

Parameters
[in]selfProtocol object whose data shall be freed.

◆ ifx_protocol_set_logger()

void ifx_protocol_set_logger ( ifx_protocol_t * self,
ifx_logger_t * logger )
related

Sets Logger to be used by Protocol.

Sets logger for whole protocol stack, so all layers below will also have the logger set.

Parameters
[in]selfProtocol object to set logger for.
[in]loggerLogger object to be used (might be NULL to clear logger).

◆ ifx_protocol_transceive()

ifx_status_t ifx_protocol_transceive ( ifx_protocol_t * self,
const uint8_t * data,
size_t data_len,
uint8_t ** response,
size_t * response_len )
related

Sends data via Protocol and reads back response.

Goes through ISO/OSI protocol stack and performs necessary protocol operations (chaining, crc, ...).

Parameters
[in]selfProtocol stack for performing necessary operations.
[in]dataData to be send via protocol.
[in]data_lenNumber of bytes in data.
[out]responseBuffer to store response in.
[out]response_lenBuffer to store number of received bytes in (number of bytes in response ).
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_t1prime_get_bwt()

ifx_status_t ifx_t1prime_get_bwt ( ifx_protocol_t * self,
uint16_t * bwt_ms_buffer )
related

Returns current block waiting time (BWT) in [ms].

Parameters
[in]selfT=1' protocol stack to get BWT for.
[out]bwt_ms_bufferBuffer to store BWT value in.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_t1prime_get_irq_handler()

ifx_status_t ifx_t1prime_get_irq_handler ( ifx_protocol_t * self,
ifx_t1prime_irq_handler_t * irq_buffer )
related

Getter for T=1' interrupt handler function.

If value is not set then polling mode is used and NULL is returned.

Parameters
[in]selfT=1' protocol stack to get interrupt handler for.
[in]irq_bufferBuffer to store interrupt handler in.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of
  • error.

◆ ifx_t1prime_initialize()

ifx_status_t ifx_t1prime_initialize ( ifx_protocol_t * self,
ifx_protocol_t * driver )
related

Initializes Protocol object for Global Platform T=1' protocol.

Parameters
[in]selfProtocol object to be initialized.
[in]driverPhysical (driver) layer used for communication.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_t1prime_set_bwt()

ifx_status_t ifx_t1prime_set_bwt ( ifx_protocol_t * self,
uint16_t bwt_ms )
related

Sets block waiting time (BWT) in [ms].

Parameters
[in]selfT=1' protocol stack to set BWT for.
[in]bwt_msBWT value to be used.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_t1prime_set_ifsd()

ifx_status_t ifx_t1prime_set_ifsd ( ifx_protocol_t * self,
size_t ifsd )
related

Sets maximum information field size of the host device (IFSD).

Parameters
[in]selfT=1' protocol stack to set IFSD for.
[in]ifsdIFS value to be used.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

◆ ifx_t1prime_set_irq_handler()

ifx_status_t ifx_t1prime_set_irq_handler ( ifx_protocol_t * self,
ifx_t1prime_irq_handler_t irq )
related

Sets T=1' interrupt handler function.

If value is not set (NULL - default) then polling mode will be used.

Parameters
[in]selfT=1' protocol stack to set interrupt handler for.
[in]irqInterrupt handler to be used.
Returns
ifx_status_t IFX_SUCCESS if successful, any other value in case of error.

Field Documentation

◆ _activate

ifx_protocol_activate_callback_t ifx_protocol_t::_activate

Private protocol activation function for negotiating protocol specific parameters.

Set by implementation's initialization function, do NOT set manually!

Can be NULL if ISO/OSI layer has no specific activation.

Definition at line 257 of file ifx-protocol.h.

◆ _base

ifx_protocol_t* ifx_protocol_t::_base

Private base layer in ISO/OSI stack.

Set by implementation's initialization function, do NOT set manually!

Definition at line 234 of file ifx-protocol.h.

◆ _destructor

ifx_protocol_destroy_callback_t ifx_protocol_t::_destructor

Private destructor if further cleanup is necessary.

Set by implementation's initialization function, do NOT set manually!

ifx_protocol_destroy() will call free() for Protocol._properties. If any further cleanup is necessary implement it in this function, otherwise use NULL.

Definition at line 302 of file ifx-protocol.h.

◆ _layer_id

uint64_t ifx_protocol_t::_layer_id

Private layer identification to verify that correct protocol layer called member functions.

Set by implementation's initialization function, do NOT set manually!

As C generics cannot differentiate on actual type, this layer ID can be used to differentiate all layers in a full ISO/OSI protocol stack.

Definition at line 246 of file ifx-protocol.h.

◆ _logger

ifx_logger_t* ifx_protocol_t::_logger

Private member for optional Logger.

Set by ifx_protocol_set_logger(), do NOT set manually!

Might be NULL.

Definition at line 311 of file ifx-protocol.h.

◆ _properties

void* ifx_protocol_t::_properties

Private member for generic properties as void*.

Only used internally, do NOT set manually!

Used to hold protocol specific properties / state. Might be NULL if no state required.

Definition at line 321 of file ifx-protocol.h.

◆ _receive

ifx_protocol_receive_callback_t ifx_protocol_t::_receive

Private function for receiving data.

Set by implementation's initialization function, do NOT set manually!

Might be NULL in which case Protocol._transceive must not be NULL.

Definition at line 290 of file ifx-protocol.h.

◆ _transceive

ifx_protocol_transceive_callback_t ifx_protocol_t::_transceive

Private function for sending and receiving data at once.

Set by implementation's initialization function, do NOT set manually!

Might be NULL in which case Protocol._transmit and Protocol._receive must no be NULL.

Definition at line 268 of file ifx-protocol.h.

◆ _transmit

ifx_protocol_transmit_callback_t ifx_protocol_t::_transmit

Private function for sending data.

Set by implementation's initialization function, do NOT set manually!

Might be NULL in which case Protocol._transceive must not be NULL.

Definition at line 279 of file ifx-protocol.h.

The documentation for this struct was generated from the following files:
Generated by doxygen 1.10.0