Infineon platform abstraction APIs

Infineon platform abstraction APIs. More...

Data Structures
struct	pal_gpio
	Structure defines the PAL GPIO configuration. More...
struct	pal_i2c
	PAL I2C context structure. More...

Macros
#define	PAL_STATUS_SUCCESS   (0x0000)
	PAL API execution is successful.
#define	PAL_STATUS_FAILURE   (0x0001)
	PAL API execution failed.
#define	PAL_STATUS_I2C_BUSY   (0x0002)
	PAL I2C is busy.
#define	PAL_I2C_EVENT_SUCCESS   (0x0000)
	Event returned when I2C master completes execution.
#define	PAL_I2C_EVENT_ERROR   (0x0001)
	Event returned when I2C master operation fails.
#define	PAL_I2C_EVENT_BUSY   (0x0002)
	Event returned when lower level I2C bus is busy.

Typedefs
typedef uint16_t	pal_status_t
	PAL return status.
typedef struct pal_gpio	pal_gpio_t
	Structure defines the PAL GPIO configuration.
typedef struct pal_i2c	pal_i2c_t
	PAL I2C context structure.
typedef void(*	register_callback )(void *)
	typedef for Callback function when timer elapses.

Functions
void	pal_gpio_set_high (const pal_gpio_t *p_gpio_context)
void	pal_gpio_set_low (const pal_gpio_t *p_gpio_context)
pal_status_t	pal_i2c_init (const pal_i2c_t *p_i2c_context)
pal_status_t	pal_i2c_set_bitrate (const pal_i2c_t *p_i2c_context, uint16_t bitrate)
pal_status_t	pal_i2c_write (pal_i2c_t *p_i2c_context, uint8_t *p_data, uint16_t length)
pal_status_t	pal_i2c_read (pal_i2c_t *p_i2c_context, uint8_t *p_data, uint16_t length)
pal_status_t	pal_i2c_deinit (const pal_i2c_t *p_i2c_context)
void	pal_os_event_register_callback_oneshot (register_callback callback, void *callback_args, uint32_t time_us)
pal_status_t	pal_os_lock_acquire (void)
	Acquires a lock. More...
void	pal_os_lock_release (void)
	Releases the lock. More...
uint32_t	pal_os_random_get_counter (void)
	Gets the random counter value.
uint32_t	pal_os_timer_get_time_in_milliseconds (void)
	Gets tick count value in milliseconds. More...
void	pal_os_timer_delay_in_milliseconds (uint16_t milliseconds)
	Waits or delay until the supplied milliseconds. More...

Variables
pal_i2c_t	optiga_pal_i2c_context_0
pal_gpio_t	optiga_vdd_0
pal_gpio_t	optiga_reset_0

Detailed Description

Infineon platform abstraction APIs.

Function Documentation

void pal_gpio_set_high

(

const pal_gpio_t *

p_gpio_context

)

Sets the gpio pin to high state

API Details: The API sets the pin high, only if the pin is assigned to a valid gpio context.
Otherwise the API returns without any failure status.

Parameters

[in]

p_gpio_context

Pointer to pal layer gpio context

void pal_gpio_set_low

(

const pal_gpio_t *

p_gpio_context

)

Sets the gpio pin to low state

API Details: The API set the pin low, only if the pin is assigned to a valid gpio context.
Otherwise the API returns without any failure status.

Parameters

[in]

p_gpio_context

Pointer to pal layer gpio context

pal_status_t pal_i2c_deinit

(

const pal_i2c_t *

p_i2c_context

)

API to de-initialize the I2C master with the specified context.

API Details:

• The platform specific de-initialization of I2C master has to be implemented as part of this API, if required.
  
• If the target platform does not demand explicit de-initialization of i2c master (Example: If the platform driver takes care of init after the reset), it would not be required to implement.
  
• The implementation must take care the following scenarios depending upon the target platform selected.
  • The implementation must handle the acquiring and releasing of the I2C bus before de-initializing the I2C master to avoid interrupting the ongoing slave I2C transactions using the same I2C master.
  • If the I2C bus is in busy state, the API must not de-initialize and return PAL_STATUS_I2C_BUSY status.
  • This API must ensure that multiple users/applications sharing the same I2C master resource is not impacted.

User Input:

• The input pal_i2c_t p_i2c_context must not be NULL.
  

Parameters

[in]

p_i2c_context

I2C context to be de-initialized

Return values

PAL_STATUS_SUCCESS	Returns when the I2C master de-init it successfull
PAL_STATUS_FAILURE	Returns when the I2C de-init fails.

pal_status_t pal_i2c_init

(

const pal_i2c_t *

p_i2c_context

)

API to initialize the i2c master with the given context.

API Details:

• The platform specific initialization of I2C master has to be implemented as part of this API, if required.
  
• If the target platform does not demand explicit initialization of i2c master (Example: If the platform driver takes care of init after the reset), it would not be required to implement.
  
• The implementation must take care the following scenarios depending upon the target platform selected.
  • The implementation must handle the acquiring and releasing of the I2C bus before initializing the I2C master to avoid interrupting the ongoing slave I2C transactions using the same I2C master.
  • If the I2C bus is in busy state, the API must not initialize and return PAL_STATUS_I2C_BUSY status.
  • Repeated initialization must be taken care with respect to the platform requirements. (Example: Multiple users/applications sharing the same I2C master resource)

User Input:

• The input pal_i2c_t p_i2c_context must not be NULL.
  

Parameters

[in]

p_i2c_context

Pal i2c context to be initialized

Return values

PAL_STATUS_SUCCESS	Returns when the I2C master init it successfull
PAL_STATUS_FAILURE	Returns when the I2C init fails.

pal_status_t pal_i2c_read	(	pal_i2c_t *	p_i2c_context,
		uint8_t *	p_data,
		uint16_t	length
	)

Platform abstraction layer API to read the data from I2C slave.

API Details:

• The API attempts to read if the I2C bus is free, else it returns busy status PAL_STATUS_I2C_BUSY
  
• The bus is released only after the completion of reception or after completion of error handling.
  
• The API invokes the upper layer handler with the respective event status as explained below.
  • PAL_I2C_EVENT_BUSY when I2C bus in busy state
  • PAL_I2C_EVENT_ERROR when API fails
  • PAL_I2C_EVENT_SUCCESS when operation is successfully completed asynchronously
    

User Input:

• The input pal_i2c_t p_i2c_context must not be NULL.
  
• The upper_layer_event_handler must be initialized in the p_i2c_context before invoking the API.
  

Notes:

• Otherwise the below implementation has to be updated to handle different bitrates based on the input context.
  
• The caller of this API must take care of the guard time based on the slave's requirement.
  

Parameters

[in]	p_i2c_context	pointer to the PAL i2c context pal_i2c_t
[in]	p_data	Pointer to the data buffer to store the read data
[in]	length	Length of the data to be read

Return values

PAL_STATUS_SUCCESS	Returns when the I2C read is invoked successfully
PAL_STATUS_FAILURE	Returns when the I2C read fails.
PAL_STATUS_I2C_BUSY	Returns when the I2C bus is busy.

pal_status_t pal_i2c_set_bitrate	(	const pal_i2c_t *	p_i2c_context,
		uint16_t	bitrate
	)

Platform abstraction layer API to set the bitrate/speed(KHz) of I2C master.

API Details:

• Sets the bitrate of I2C master if the I2C bus is free, else it returns busy status PAL_STATUS_I2C_BUSY
  
• The bus is released after the setting the bitrate.
  
• This API must take care of setting the bitrate to I2C master's maximum supported value.
• Eg. In XMC4500, the maximum supported bitrate is 400 KHz. If the supplied bitrate is greater than 400KHz, the API will set the I2C master's bitrate to 400KHz.
• Use the PAL_I2C_MASTER_MAX_BITRATE macro to specify the maximum supported bitrate value for the target platform.
• If upper_layer_event_handler is initialized, the upper layer handler is invoked with the respective event status listed below.
  • PAL_I2C_EVENT_BUSY when I2C bus in busy state
  • PAL_I2C_EVENT_ERROR when API fails to set the bit rate
  • PAL_I2C_EVENT_SUCCESS when operation is successful
    

User Input:

• The input pal_i2c_t p_i2c_context must not be NULL.
  

Parameters

[in]	p_i2c_context	Pointer to the pal i2c context
[in]	bitrate	Bitrate in KHz

Return values

PAL_STATUS_SUCCESS	Returns when the setting of bitrate is successfully completed
PAL_STATUS_FAILURE	Returns when the setting of bitrate fails.
PAL_STATUS_I2C_BUSY	Returns when the I2C bus is busy.

pal_status_t pal_i2c_write	(	pal_i2c_t *	p_i2c_context,
		uint8_t *	p_data,
		uint16_t	length
	)

Platform abstraction layer API to write the data to I2C slave.

API Details:

• The API attempts to write if the I2C bus is free, else it returns busy status PAL_STATUS_I2C_BUSY
  
• The bus is released only after the completion of transmission or after completion of error handling.
  
• The API invokes the upper layer handler with the respective event status as explained below.
  • PAL_I2C_EVENT_BUSY when I2C bus in busy state
  • PAL_I2C_EVENT_ERROR when API fails
  • PAL_I2C_EVENT_SUCCESS when operation is successfully completed asynchronously
    

User Input:

• The input pal_i2c_t p_i2c_context must not be NULL.
  
• The upper_layer_event_handler must be initialized in the p_i2c_context before invoking the API.
  

Notes:

• Otherwise the below implementation has to be updated to handle different bitrates based on the input context.
  
• The caller of this API must take care of the guard time based on the slave's requirement.
  

Parameters

[in]	p_i2c_context	Pointer to the pal I2C context pal_i2c_t
[in]	p_data	Pointer to the data to be written
[in]	length	Length of the data to be written

Return values

PAL_STATUS_SUCCESS	Returns when the I2C write is invoked successfully
PAL_STATUS_FAILURE	Returns when the I2C write fails.
PAL_STATUS_I2C_BUSY	Returns when the I2C bus is busy.

void pal_os_event_register_callback_oneshot	(	register_callback	callback,
		void *	callback_args,
		uint32_t	time_us
	)

Platform specific event call back registration function to trigger once when timer expires.

API Details: This function registers the callback function supplied by the caller.
It triggers a timer with the supplied time interval in microseconds.
Once the timer expires, the registered callback function gets called.

Parameters

[in]	callback	Callback function pointer
[in]	callback_args	Callback arguments
[in]	time_us	time in micro seconds to trigger the call back

pal_status_t pal_os_lock_acquire

(

void

)

Acquires a lock.

Pre-conditions: None.

API Details:

• Acquires the lock.
  
  

void pal_os_lock_release

(

void

)

Releases the lock.

Pre-conditions: None.

API Details:

• Releases the lock.
  
  

void pal_os_timer_delay_in_milliseconds

(

uint16_t

milliseconds

)

Waits or delay until the supplied milliseconds.

Parameters

[in]

milliseconds

Delay value in milliseconds

uint32_t pal_os_timer_get_time_in_milliseconds

(

void

)

Gets tick count value in milliseconds.

Return values

uint32_t

time in milliseconds