| ipipsu Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

Macros | Functions
IPIPSU APIs

## Macros
#define | XIPIPSU_HW_H_
| < prevent circular inclusions More...
#define | XIPIPSU_MSG_RAM_BASE 0xFF990000U
| IPI Message RAM base address. More...
#define | XIPIPSU_MSG_BUF_SIZE 8U
| Buffer size for up to 8 messages, each 4-bytes long. More...
#define | XIPIPSU_MAX_BUFF_INDEX 7U
| Maximum Buffer Index. More...
#define | XIPIPSU_BUFFER_OFFSET_GROUP (8U * 2U * 32U)
| Buffer offset for group. More...
#define | XIPIPSU_BUFFER_OFFSET_TARGET (32U * 2U)
| Buffer offset for target. More...
#define | XIPIPSU_BUFFER_OFFSET_RESPONSE (32U)
| Buffer offset for response. More...
#define | XIPIPSU_MAX_TARGETS XPAR_XIPIPSU_NUM_TARGETS
| Maximum number of targets. More...
#define | XIPIPSU_TRIG_OFFSET 0x00U
| Offset for Trigger register. More...
#define | XIPIPSU_OBS_OFFSET 0x04U
| Offset for Observation register. More...
#define | XIPIPSU_ISR_OFFSET 0x10U
| Offset for ISR register. More...
#define | XIPIPSU_IMR_OFFSET 0x14U
| Offset for Interrupt Mask Register. More...
#define | XIPIPSU_IER_OFFSET 0x18U
| Offset for Interrupt Enable Register. More...
#define | XIPIPSU_IDR_OFFSET 0x1CU
| Offset for Interrupt Disable Register. More...
#define | XIPIPSU_ECC_UE_MASK 0x40U
| Uncorrecteble Error mask. More...
#define | XIPIPSU_ALL_MASK 0x0F0F0301U
| All valid bit mask. More...

## Functions
XStatus | XIpiPsu_CfgInitialize (XIpiPsu *InstancePtr, XIpiPsu_Config *CfgPtr, UINTPTR EffectiveAddress)
| Initializes the Instance pointer based on a given Config Pointer. More...
void | XIpiPsu_Reset (XIpiPsu *InstancePtr)
| Resets the given IPI register set. More...
XStatus | XIpiPsu_TriggerIpi (XIpiPsu *InstancePtr, u32 DestCpuMask)
| Triggers an IPI to a Destination CPU. More...
XStatus | XIpiPsu_PollForAck (const XIpiPsu *InstancePtr, u32 DestCpuMask, u32 TimeOutCount)
| Polls for an acknowledgement using Observation Register. More...
XStatus | XIpiPsu_ReadMessage (XIpiPsu *InstancePtr, u32 SrcCpuMask, u32 *MsgPtr, u32 MsgLength, u8 BufferType)
| Read an Incoming Message from a Source. More...
XStatus | XIpiPsu_WriteMessage (XIpiPsu *InstancePtr, u32 DestCpuMask, const u32 *MsgPtr, u32 MsgLength, u8 BufferType)
| Sends a Message to Destination. More...
void | XIpiPsu_SetConfigTable (u32 DeviceId, XIpiPsu_Config *ConfigTblPtr)
| Sets up the device configuration based on the unique device ID. More...
u32 * | XIpiPsu_GetBufferAddress (XIpiPsu *InstancePtr, u32 SrcCpuMask, u32 DestCpuMask, u32 BufferType)
| Gets the Buffer Address for a given pair of CPUs. More...
u32 | XIpiPsu_GetBufferIndex (const XIpiPsu *InstancePtr, u32 CpuMask)
| Gets the Buffer Index for a CPU specified by Mask. More...
XIpiPsu_Config * | XIpiPsu_LookupConfig (u32 DeviceId)
| Looks up the device configuration based on the unique device ID. More...

## Macro Definition Documentation

#define XIPIPSU_ALL_MASK 0x0F0F0301U

All valid bit mask.

Referenced by main(), and XIpiPsu_Reset().

#define XIPIPSU_BUFFER_OFFSET_GROUP (8U * 2U * 32U)

Buffer offset for group.

Referenced by XIpiPsu_GetBufferAddress().

#define XIPIPSU_BUFFER_OFFSET_RESPONSE (32U)

Buffer offset for response.

Referenced by XIpiPsu_GetBufferAddress().

#define XIPIPSU_BUFFER_OFFSET_TARGET (32U * 2U)

Buffer offset for target.

Referenced by XIpiPsu_GetBufferAddress().

#define XIPIPSU_ECC_UE_MASK 0x40U

Uncorrecteble Error mask.

#define XIPIPSU_HW_H_

< prevent circular inclusions

by using protection macros

#define XIPIPSU_IDR_OFFSET 0x1CU

Offset for Interrupt Disable Register.

Referenced by XIpiPsu_Reset().

#define XIPIPSU_IER_OFFSET 0x18U

Offset for Interrupt Enable Register.

#define XIPIPSU_IMR_OFFSET 0x14U

Offset for Interrupt Mask Register.

#define XIPIPSU_ISR_OFFSET 0x10U

Offset for ISR register.

Referenced by XIpiPsu_Reset().

#define XIPIPSU_MAX_BUFF_INDEX 7U

Maximum Buffer Index.

Referenced by XIpiPsu_GetBufferAddress(), and XIpiPsu_GetBufferIndex().

#define XIPIPSU_MAX_TARGETS XPAR_XIPIPSU_NUM_TARGETS

Maximum number of targets.

#define XIPIPSU_MSG_BUF_SIZE 8U

Buffer size for up to 8 messages, each 4-bytes long.

#define XIPIPSU_MSG_RAM_BASE 0xFF990000U

IPI Message RAM base address.

Referenced by XIpiPsu_GetBufferAddress().

#define XIPIPSU_OBS_OFFSET 0x04U

Offset for Observation register.

Referenced by XIpiPsu_PollForAck().

#define XIPIPSU_TRIG_OFFSET 0x00U

Offset for Trigger register.

Referenced by XIpiPsu_TriggerIpi().

## Function Documentation

XStatus XIpiPsu_CfgInitialize | ( | XIpiPsu * | InstancePtr,
|  | XIpiPsu_Config * | CfgPtr,
|  | UINTPTR | EffectiveAddress
| ) |  |

Initializes the Instance pointer based on a given Config Pointer.

Parameters

  InstancePtr | Pointer to the instance to be worked on
  CfgPtr | Device configuration structure containing required hardware build data
  EffectiveAddress | Base address of the device. If address translation is not utilized, this parameter can be passed in using CfgPtr->Config. BaseAddress to specify the physical base address.

Returns
  XST_SUCCESS if initialization was successful XST_FAILURE in case of failure

References XIpiPsu_Config::BaseAddress, XIpiPsu_Config::BitMask, XIpiPsu_Target::BufferIndex, XIpiPsu_Config::BufferIndex, XIpiPsu::Config, XIpiPsu_Config::DeviceId, XIpiPsu_Config::IntId, XIpiPsu::IsReady, XIpiPsu_Target::Mask, XIpiPsu_Config::TargetCount, and XIpiPsu_Config::TargetList.

Referenced by main().

u32* XIpiPsu_GetBufferAddress | ( | XIpiPsu * | InstancePtr,
|  | u32 | SrcCpuMask,
|  | u32 | DestCpuMask,
|  | u32 | BufferType
| ) |  |

Gets the Buffer Address for a given pair of CPUs.

Parameters

  InstancePtr | Pointer to current IPI instance
  SrcCpuMask | Mask for Source CPU
  DestCpuMask | Mask for Destination CPU
  BufferType | Type of buffer either XIPIPSU_BUF_TYPE_MSG or XIPIPSU_BUF_TYPE_RESP

Returns
  Valid Buffer Address if no error NULL if an error occurs in calculating address

References XIPIPSU_BUF_TYPE_MSG, XIPIPSU_BUF_TYPE_RESP, XIPIPSU_BUFFER_OFFSET_GROUP, XIPIPSU_BUFFER_OFFSET_RESPONSE, XIPIPSU_BUFFER_OFFSET_TARGET, XIpiPsu_GetBufferIndex(), XIPIPSU_MAX_BUFF_INDEX, and XIPIPSU_MSG_RAM_BASE.

Referenced by XIpiPsu_ReadMessage(), and XIpiPsu_WriteMessage().

u32 XIpiPsu_GetBufferIndex | ( | const XIpiPsu * | InstancePtr,
|  | u32 | CpuMask
| ) |  |

Gets the Buffer Index for a CPU specified by Mask.

Parameters

  InstancePtr | Pointer to current IPI instance
  CpuMask | Mask of the CPU form which Index is required

Returns
  Buffer Index value if CPU Mask is valid XIPIPSU_MAX_BUFF_INDEX+1 if not valid

References XIpiPsu_Target::BufferIndex, XIpiPsu::Config, XIpiPsu_Target::Mask, XIpiPsu_Config::TargetCount, XIpiPsu_Config::TargetList, and XIPIPSU_MAX_BUFF_INDEX.

Referenced by XIpiPsu_GetBufferAddress().

XIpiPsu_Config* XIpiPsu_LookupConfig | ( | u32 | DeviceId | ) |

Looks up the device configuration based on the unique device ID.

A table contains the configuration information for each device in the system.

Parameters

  DeviceId | Contains the ID of the device to look up the configuration for.

Returns
  A pointer to the configuration found or NULL if the specified device ID was not found. See xipipsu.h for the definition of XIpiPsu_Config.

Note
  None.

References XIpiPsu_ConfigTable.

Referenced by main().

XStatus XIpiPsu_PollForAck | ( | const XIpiPsu * | InstancePtr,
|  | u32 | DestCpuMask,
|  | u32 | TimeOutCount
| ) |  |

Polls for an acknowledgement using Observation Register.

Parameters

  InstancePtr | Pointer to current IPI instance
  DestCpuMask | Mask of the destination CPU from which ACK is expected
  TimeOutCount | Count after which the routines returns failure

Returns
  XST_SUCCESS if successful XST_FAILURE if a timeout occurred

References XIpiPsu_Config::BaseAddress, XIpiPsu::Config, XIpiPsu::IsReady, XIPIPSU_OBS_OFFSET, and XIpiPsu_ReadReg.

XStatus XIpiPsu_ReadMessage | ( | XIpiPsu * | InstancePtr,
|  | u32 | SrcCpuMask,
|  | u32 * | MsgPtr,
|  | u32 | MsgLength,
|  | u8 | BufferType
| ) |  |

Read an Incoming Message from a Source.

Parameters

  InstancePtr | Pointer to current IPI instance
  SrcCpuMask | Device Mask for the CPU which has sent the message
  MsgPtr | Pointer to Buffer to which the read message needs to be stored
  MsgLength | Number of messages (each message is 4bytes)
  BufferType | Type of buffer (XIPIPSU_BUF_TYPE_MSG or XIPIPSU_BUF_TYPE_RESP)

Returns
  XST_SUCCESS if successful XST_FAILURE if an error occurred

References XIpiPsu_Config::BitMask, XIpiPsu::Config, XIpiPsu::IsReady, XIPIPSU_CRC_ERROR, XIPIPSU_CRC_INDEX, XIpiPsu_GetBufferAddress(), XIPIPSU_MAX_MSG_LEN, and XIPIPSU_W0_TO_W6_SIZE.

Referenced by IpiIntrHandler().

void XIpiPsu_Reset | ( | XIpiPsu * | InstancePtr | ) |

Resets the given IPI register set.

        This function can be called to disable the IPIs from all
        the sources and clear any pending IPIs in status register

Parameters

  InstancePtr | Pointer to current IPI instance

References XIpiPsu_Config::BaseAddress, XIpiPsu::Config, XIpiPsu::IsReady, XIPIPSU_ALL_MASK, XIPIPSU_IDR_OFFSET, XIPIPSU_ISR_OFFSET, and XIpiPsu_WriteReg.

void XIpiPsu_SetConfigTable | ( | u32 | DeviceId,
|  | XIpiPsu_Config * | ConfigTblPtr
| ) |  |

Sets up the device configuration based on the unique device ID.

A table contains the configuration info for each device in the system.

Parameters

  DeviceId | Contains the ID of the device to set up the configuration for.
  ConfigTblPtr | Device configuration structure containing required hardware build data

Returns
  A pointer to the device configuration for the specified device ID. See xipipsu.h for the definition of XIpiPsu_Config.

Note
  This is for safety use case where in this function has to be called before CfgInitialize so that driver will be initialized with the provided configuration. For non-safe use cases, this is not required.

References XIpiPsu_Config::BaseAddress, XIpiPsu_Config::BitMask, XIpiPsu_Config::BufferIndex, XIpiPsu_Config::IntId, and XIpiPsu_ConfigTable.

XStatus XIpiPsu_TriggerIpi | ( | XIpiPsu * | InstancePtr,
|  | u32 | DestCpuMask
| ) |  |

Triggers an IPI to a Destination CPU.

Parameters

  InstancePtr | Pointer to current IPI instance
  DestCpuMask | Mask of the CPU to which IPI is to be triggered

Returns
  XST_SUCCESS if successful XST_FAILURE if an error occurred

References XIpiPsu_Config::BaseAddress, XIpiPsu::Config, XIpiPsu::IsReady, XIPIPSU_TRIG_OFFSET, and XIpiPsu_WriteReg.

XStatus XIpiPsu_WriteMessage | ( | XIpiPsu * | InstancePtr,
|  | u32 | DestCpuMask,
|  | const u32 * | MsgPtr,
|  | u32 | MsgLength,
|  | u8 | BufferType
| ) |  |

Sends a Message to Destination.

Parameters

  InstancePtr | Pointer to current IPI instance
  DestCpuMask | Device Mask for the destination CPU
  MsgPtr | Pointer to Buffer which contains the message to be sent
  MsgLength | Number of messages (each message is 4bytes)
  BufferType | Type of buffer (XIPIPSU_BUF_TYPE_MSG or XIPIPSU_BUF_TYPE_RESP)

Returns
  XST_SUCCESS if successful XST_FAILURE if an error occurred

References XIpiPsu_Config::BitMask, XIpiPsu::Config, XIpiPsu::IsReady, XIPIPSU_CRC_INDEX, XIpiPsu_GetBufferAddress(), XIPIPSU_MAX_MSG_LEN, and XIPIPSU_W0_TO_W6_SIZE.

Referenced by IpiIntrHandler().