pal_i2c.h File Reference

This file provides the prototype declarations of PAL I2C. More...

#include "pal.h"

Include dependency graph for pal_i2c.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	pal_i2c
	PAL I2C context structure. More...
#define	PAL_I2C_EVENT_SUCCESS   (0x0000)
	Event returned when I2C master completes execution. More...
#define	PAL_I2C_EVENT_ERROR   (0x0001)
	Event returned when I2C master operation fails. More...
#define	PAL_I2C_EVENT_BUSY   (0x0002)
	Event returned when lower level I2C bus is busy. More...
typedef struct pal_i2c	pal_i2c_t
	PAL I2C context structure. More...
LIBRARY_EXPORTS pal_status_t	pal_i2c_init (const pal_i2c_t *p_i2c_context)
	Initializes the I2C master. More...
LIBRARY_EXPORTS pal_status_t	pal_i2c_set_bitrate (const pal_i2c_t *p_i2c_context, uint16_t bitrate)
	Sets the I2C Master bitrate. More...
LIBRARY_EXPORTS pal_status_t	pal_i2c_write (pal_i2c_t *p_i2c_context, uint8_t *p_data, uint16_t length)
	Writes on I2C bus. More...
LIBRARY_EXPORTS pal_status_t	pal_i2c_read (pal_i2c_t *p_i2c_context, uint8_t *p_data, uint16_t length)
	Reads from I2C bus. More...
LIBRARY_EXPORTS pal_status_t	pal_i2c_deinit (const pal_i2c_t *p_i2c_context)
	De-initializes the I2C master. More...

Detailed Description

This file provides the prototype declarations of PAL I2C.

Copyright

MIT License

Copyright (c) 2019 Infineon Technologies AG

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

\endcopyright

Author

Infineon Technologies AG

Macro Definition Documentation

PAL_I2C_EVENT_BUSY

#define PAL_I2C_EVENT_BUSY   (0x0002)

Event returned when lower level I2C bus is busy.

PAL_I2C_EVENT_ERROR

#define PAL_I2C_EVENT_ERROR   (0x0001)

Event returned when I2C master operation fails.

PAL_I2C_EVENT_SUCCESS

#define PAL_I2C_EVENT_SUCCESS   (0x0000)

Event returned when I2C master completes execution.

Typedef Documentation

pal_i2c_t

typedef struct pal_i2c pal_i2c_t

PAL I2C context structure.

Function Documentation

pal_i2c_deinit()

LIBRARY_EXPORTS pal_status_t pal_i2c_deinit

(

const pal_i2c_t *

p_i2c_context

)

De-initializes the I2C master.

De-initializes the I2C master with the specified context.

• 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.

Precondition

• None

Note

• None

Parameters

[in]

p_i2c_context

Valid pointer to the PAL I2C context that should be de-initialized

Return values

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

pal_i2c_init()

LIBRARY_EXPORTS pal_status_t pal_i2c_init

(

const pal_i2c_t *

p_i2c_context

)

Initializes the I2C master.

Initializes the I2C master with the given context.

• 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)

Precondition

• None

Note

• None

Parameters

[in]

p_i2c_context

Valid pointer to the PAL I2C context that should be initialized

Return values

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

pal_i2c_read()

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

Reads from I2C bus.

Reads the data from I2C slave.

pal_i2c_read()

• 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
    

Precondition

• None

Note

• 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_i2c_set_bitrate()

LIBRARY_EXPORTS pal_status_t pal_i2c_set_bitrate	(	const pal_i2c_t *	p_i2c_context,
		uint16_t	bitrate
	)

Sets the I2C Master bitrate.

Sets the bitrate/speed(KHz) of I2C master.

• 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 XMC4800, 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.
• 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
    

Precondition

• None

Note

• None

Parameters

[in]	p_i2c_context	Valid pointer to the PAL I2C context
[in]	bitrate	Bitrate to be used by I2C master 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_i2c_write()

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

Writes on I2C bus.

Writes the data to I2C slave.

pal_i2c_write()

• 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
    

Precondition

• None

Note

• 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.
  
• The upper_layer_event_handler must be initialized in the p_i2c_context before invoking the API.
  

Parameters

[in]	p_i2c_context	Valid 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.