| ipipsu Vitis Drivers API Documentation

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

Data Structures | Macros | Functions | Variables
Overview

## Data Structures
struct | XIpiPsu_Target
| Data structure used to refer IPI Targets. More...
struct | XIpiPsu_Config
| This typedef contains configuration information for the device. More...
struct | XIpiPsu
| The XIpiPsu driver instance data. More...

## Macros
#define | XIPIPSU_BUF_TYPE_MSG (0x001U)
| Message type buffer. More...
#define | XIPIPSU_BUF_TYPE_RESP (0x002U)
| Response buffer. More...
#define | XIPIPSU_CRC_INDEX (0x7U)
| Index where the CRC is stored. More...
#define | XIPIPSU_W0_TO_W6_SIZE (28U)
| Size of the word 0 to word 6. More...
#define | XIPIPSU_CRC_ERROR (0xFL)
| CRC error occurred. More...
#define | ENABLE_IPI_CRC_VAL (0x0U)
| Enable CRC. More...
#define | XIPIPSU_MAX_MSG_LEN XIPIPSU_MSG_BUF_SIZE
| Maximum message length. More...
#define | XIpiPsu_ReadReg(BaseAddress, RegOffset) Xil_In32((BaseAddress) + (RegOffset))
| Reads the register specified by the base address and offset. More...
#define | XIpiPsu_WriteReg(BaseAddress, RegOffset, Data) Xil_Out32(((BaseAddress) + (RegOffset)), (Data))
| Writes a value into a register specified by base address and offset. More...
#define | XIpiPsu_InterruptEnable(InstancePtr, Mask)
| Enable interrupts specified in Mask. More...
#define | XIpiPsu_InterruptDisable(InstancePtr, Mask)
| Disable interrupts specified in Mask. More...
#define | XIpiPsu_GetInterruptStatus(InstancePtr)
| Gets the STATUS REGISTER of the current IPI instance. More...
#define | XIpiPsu_ClearInterruptStatus(InstancePtr, Mask)
| Clears the STATUS REGISTER of the current IPI instance. More...
#define | XIpiPsu_GetObsStatus(InstancePtr)
| Gets the OBSERVATION REGISTER of the current IPI instance. More...

## Functions
XIpiPsu_Config * | XIpiPsu_LookupConfig (u32 DeviceId)
| Looks up the device configuration based on the unique device ID. More...
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...

## Variables
XIpiPsu_Config | XIpiPsu_ConfigTable [XPAR_XIPIPSU_NUM_INSTANCES]
| The IPIPSU configuration table, sized by the number of instances defined in xparameters.h. More...

## Macro Definition Documentation

#define ENABLE_IPI_CRC_VAL (0x0U)

Enable CRC.

#define XIPIPSU_BUF_TYPE_MSG (0x001U)

Message type buffer.

Referenced by IpiIntrHandler(), and XIpiPsu_GetBufferAddress().

#define XIPIPSU_BUF_TYPE_RESP (0x002U)

Response buffer.

Referenced by IpiIntrHandler(), and XIpiPsu_GetBufferAddress().

#define XIpiPsu_ClearInterruptStatus | ( |  | InstancePtr,
|  |  | Mask
| ) |  |

Value:
XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
XIPIPSU_ISR_OFFSET, \
((Mask) & XIPIPSU_ALL_MASK));
XIpiPsu_WriteReg
#define XIpiPsu_WriteReg(BaseAddress, RegOffset, Data)
Writes a value into a register specified by base address and offset.
Definition: xipipsu.h:199
XIPIPSU_ALL_MASK
#define XIPIPSU_ALL_MASK
All valid bit mask.
Definition: xipipsu_hw.h:93
XIPIPSU_ISR_OFFSET
#define XIPIPSU_ISR_OFFSET
Offset for ISR register.
Definition: xipipsu_hw.h:73

Clears the STATUS REGISTER of the current IPI instance.

The corresponding interrupt status for each bit set to 1 in Mask is cleared.

Parameters

  InstancePtr | Pointer to the instance to be worked on.
  Mask | Mask corresponding to the source CPU*

Note
  This function should be used after handling the IPI. Clearing the status will automatically clear the corresponding bit in OBSERVATION register of Source CPU C-style signature void XIpiPsu_ClearInterruptStatus(XIpiPsu *InstancePtr, u32 Mask)

Referenced by IpiIntrHandler(), and main().

#define XIPIPSU_CRC_ERROR (0xFL)

CRC error occurred.

Referenced by XIpiPsu_ReadMessage().

#define XIPIPSU_CRC_INDEX (0x7U)

Index where the CRC is stored.

Referenced by XIpiPsu_ReadMessage(), and XIpiPsu_WriteMessage().

#define XIpiPsu_GetInterruptStatus | ( |  | InstancePtr | ) |

Value:
XIpiPsu_ReadReg((InstancePtr)->Config.BaseAddress, \
XIPIPSU_ISR_OFFSET)
XIPIPSU_ISR_OFFSET
#define XIPIPSU_ISR_OFFSET
Offset for ISR register.
Definition: xipipsu_hw.h:73
XIpiPsu_ReadReg
#define XIpiPsu_ReadReg(BaseAddress, RegOffset)
Reads the register specified by the base address and offset.
Definition: xipipsu.h:181

Gets the STATUS REGISTER of the current IPI instance.

Parameters

  InstancePtr | Pointer to the instance to be worked on.

Returns
  Returns the Interrupt Status register(ISR) contents

Note
  User needs to parse this 32-bit value to check the source CPU C-style signature u32 XIpiPsu_GetInterruptStatus(XIpiPsu *InstancePtr)

Referenced by IpiIntrHandler().

#define XIpiPsu_GetObsStatus | ( |  | InstancePtr | ) |

Value:
XIpiPsu_ReadReg((InstancePtr)->Config.BaseAddress, \
XIPIPSU_OBS_OFFSET)
XIPIPSU_OBS_OFFSET
#define XIPIPSU_OBS_OFFSET
Offset for Observation register.
Definition: xipipsu_hw.h:72
XIpiPsu_ReadReg
#define XIpiPsu_ReadReg(BaseAddress, RegOffset)
Reads the register specified by the base address and offset.
Definition: xipipsu.h:181

Gets the OBSERVATION REGISTER of the current IPI instance.

Parameters

  InstancePtr | Pointer to the instance to be worked on.

Returns
  Returns the Observation register(OBS) contents

Note
  User needs to parse this 32-bit value to check the status of individual CPUs C-style signature u32 XIpiPsu_GetObsStatus(XIpiPsu *InstancePtr)

#define XIpiPsu_InterruptDisable | ( |  | InstancePtr,
|  |  | Mask
| ) |  |

Value:
XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
XIPIPSU_IDR_OFFSET, \
((Mask) & XIPIPSU_ALL_MASK));
XIPIPSU_IDR_OFFSET
#define XIPIPSU_IDR_OFFSET
Offset for Interrupt Disable Register.
Definition: xipipsu_hw.h:76
XIpiPsu_WriteReg
#define XIpiPsu_WriteReg(BaseAddress, RegOffset, Data)
Writes a value into a register specified by base address and offset.
Definition: xipipsu.h:199
XIPIPSU_ALL_MASK
#define XIPIPSU_ALL_MASK
All valid bit mask.
Definition: xipipsu_hw.h:93

Disable interrupts specified in Mask.

The corresponding interrupt for each bit set to 1 in Mask, will be disabled.

Parameters

  InstancePtr | Pointer to the instance to be worked on.
  Mask | Contains a bit mask of interrupts to disable. The mask can be formed using a set of bitwise or'd values of individual CPU masks

Note
  C-style signature void XIpiPsu_InterruptDisable(XIpiPsu *InstancePtr, u32 Mask)

#define XIpiPsu_InterruptEnable | ( |  | InstancePtr,
|  |  | Mask
| ) |  |

Value:
XIpiPsu_WriteReg((InstancePtr)->Config.BaseAddress, \
XIPIPSU_IER_OFFSET, \
((Mask) & XIPIPSU_ALL_MASK));
XIpiPsu_WriteReg
#define XIpiPsu_WriteReg(BaseAddress, RegOffset, Data)
Writes a value into a register specified by base address and offset.
Definition: xipipsu.h:199
XIPIPSU_ALL_MASK
#define XIPIPSU_ALL_MASK
All valid bit mask.
Definition: xipipsu_hw.h:93
XIPIPSU_IER_OFFSET
#define XIPIPSU_IER_OFFSET
Offset for Interrupt Enable Register.
Definition: xipipsu_hw.h:75

Enable interrupts specified in Mask.

The corresponding interrupt for each bit set to 1 in Mask, will be enabled.

Parameters

  InstancePtr | Pointer to the instance to be worked on.
  Mask | Contains a bit mask of interrupts to enable. The mask can be formed using a set of bitwise or'd values of individual CPU masks

Note
  C-style signature void XIpiPsu_InterruptEnable(XIpiPsu *InstancePtr, u32 Mask)

Referenced by main().

#define XIPIPSU_MAX_MSG_LEN XIPIPSU_MSG_BUF_SIZE

Maximum message length.

Referenced by XIpiPsu_ReadMessage(), and XIpiPsu_WriteMessage().

#define XIpiPsu_ReadReg | ( |  | BaseAddress,
|  |  | RegOffset
| ) |  | Xil_In32((BaseAddress) + (RegOffset))

Reads the register specified by the base address and offset.

Parameters

  BaseAddress | Base address of the IPI instance
  RegOffset | Offset of the register relative to base

Returns
  Value of the specified register

Note
  C-style signature u32 XIpiPsu_ReadReg(u32 BaseAddress, u32 RegOffset)

Referenced by XIpiPsu_PollForAck().

#define XIPIPSU_W0_TO_W6_SIZE (28U)

Size of the word 0 to word 6.

Referenced by XIpiPsu_ReadMessage(), and XIpiPsu_WriteMessage().

#define XIpiPsu_WriteReg | ( |  | BaseAddress,
|  |  | RegOffset,
|  |  | Data
| ) |  | Xil_Out32(((BaseAddress) + (RegOffset)), (Data))

Writes a value into a register specified by base address and offset.

Parameters

  BaseAddress | Base address of the IPI instance
  RegOffset | Offset of the register relative to base
  Data | 32-bit value that is to be written into the specified register

Note
  C-style signature void XIpiPsu_WriteReg(u32 BaseAddress, u32 RegOffset, u32 Data)

Referenced by XIpiPsu_Reset(), and 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().

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().

## Variable Documentation

XIpiPsu_Config XIpiPsu_ConfigTable[XPAR_XIPIPSU_NUM_INSTANCES]

The IPIPSU configuration table, sized by the number of instances defined in xparameters.h.

Referenced by XIpiPsu_LookupConfig(), and XIpiPsu_SetConfigTable().