| gpio Vitis Drivers API Documentation

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

Data Structures | Macros | Functions | Variables
GPIO APIs

## Data Structures
struct | XGpio_Config
| This typedef contains configuration information for the device. More...
struct | XGpio
| The XGpio driver instance data. More...

## Macros
#define | XGPIO_H
| by using protection macros More...
#define | XGPIO_I_H
| by using protection macros More...
#define | XGPIO_L_H
| by using protection macros More...
#define | XGPIO_CHAN_OFFSET 8
| Channel offeset. More...
#define | XGpio_In32 Xil_In32
| Input Operations. More...
#define | XGpio_Out32 Xil_Out32
| Output Operations. More...
#define | XGpio_WriteReg(BaseAddress, RegOffset, Data) XGpio_Out32((BaseAddress) + (RegOffset), (u32)(Data))
| Performs a 32-bit write to a GPIO register. More...
#define | XGpio_ReadReg(BaseAddress, RegOffset) XGpio_In32((BaseAddress) + (RegOffset))
| Reads a value from a GPIO register. More...
#define | XPAR_XGPIO_NUM_INSTANCES 0
| GPIO instances. More...

## Functions
int | XGpio_CfgInitialize (XGpio *InstancePtr, XGpio_Config *Config, UINTPTR EffectiveAddr)
| Initializes the XGpio instance provided by the caller based on the given configuration data. More...
void | XGpio_SetDataDirection (XGpio *InstancePtr, unsigned Channel, u32 DirectionMask)
| Sets the input/output direction of all discrete signals for the specified GPIO channel. More...
u32 | XGpio_GetDataDirection (XGpio *InstancePtr, unsigned Channel)
| Gets the input/output direction of all discrete signals for the specified GPIO channel. More...
u32 | XGpio_DiscreteRead (XGpio *InstancePtr, unsigned Channel)
| Reads state of discretes for the specified GPIO channel. More...
void | XGpio_DiscreteWrite (XGpio *InstancePtr, unsigned Channel, u32 Mask)
| Writes to discretes register for the specified GPIO channel. More...
int | XGpio_Initialize (XGpio *InstancePtr, u16 DeviceId)
| Initializes the XGpio instance provided by the caller based on the given DeviceID. More...
XGpio_Config * | XGpio_LookupConfig (u16 DeviceId)
| Lookup the device configuration based on the unique device ID. More...
void | XGpio_DiscreteSet (XGpio *InstancePtr, unsigned Channel, u32 Mask)
| Set output discrete(s) to logic 1 for the specified GPIO channel. More...
void | XGpio_DiscreteClear (XGpio *InstancePtr, unsigned Channel, u32 Mask)
| Set output discrete(s) to logic 0 for the specified GPIO channel. More...
int | XGpio_SelfTest (XGpio *InstancePtr)
| Runs a self-test on the driver/device. More...
void | XGpio_InterruptGlobalEnable (XGpio *InstancePtr)
| Enables the interrupt output signal. More...
void | XGpio_InterruptGlobalDisable (XGpio *InstancePtr)
| Disables the interrupt output signal. More...
void | XGpio_InterruptEnable (XGpio *InstancePtr, u32 Mask)
| Enable interrupts. More...
void | XGpio_InterruptDisable (XGpio *InstancePtr, u32 Mask)
| Disable interrupts. More...
void | XGpio_InterruptClear (XGpio *InstancePtr, u32 Mask)
| Clears pending interrupts with the provided mask. More...
u32 | XGpio_InterruptGetEnabled (XGpio *InstancePtr)
| Returns the interrupt enable mask. More...
u32 | XGpio_InterruptGetStatus (XGpio *InstancePtr)
| Returns the status of interrupt signals. More...

## Variables
XGpio_Config | XGpio_ConfigTable []
| This table contains configuration information for each GPIO device in the system. More...
XGpio_Config | XGpio_ConfigTable []
| This table contains configuration information for each GPIO device in the system. More...

## Registers
Register offsets for this device.
#define | XGPIO_DATA_OFFSET 0x0
| Data register for 1st channel. More...
#define | XGPIO_TRI_OFFSET 0x4
| I/O direction reg for 1st channel. More...
#define | XGPIO_DATA2_OFFSET 0x8
| Data register for 2nd channel. More...
#define | XGPIO_TRI2_OFFSET 0xC
| I/O direction reg for 2nd channel. More...
#define | XGPIO_GIE_OFFSET 0x11C
| Glogal interrupt enable register. More...
#define | XGPIO_ISR_OFFSET 0x120
| Interrupt status register. More...
#define | XGPIO_IER_OFFSET 0x128
| Interrupt enable register. More...

## Interrupt Status and Enable Register bitmaps and masks
Bit definitions for the interrupt status register and interrupt enable registers.
#define | XGPIO_IR_MASK 0x3
| Mask of all bits. More...
#define | XGPIO_IR_CH1_MASK 0x1
| Mask for the 1st channel. More...
#define | XGPIO_IR_CH2_MASK 0x2
| Mask for the 2nd channel. More...

## Global Interrupt Enable Register bitmaps and masks
Bit definitions for the Global Interrupt Enable register
#define | XGPIO_GIE_GINTR_ENABLE_MASK 0x80000000
| Mask for Global Interrupt. More...

## Macro Definition Documentation

#define XGPIO_CHAN_OFFSET 8

Channel offeset.

Referenced by main(), XGpio_DiscreteClear(), XGpio_DiscreteRead(), XGpio_DiscreteSet(), XGpio_DiscreteWrite(), XGpio_GetDataDirection(), and XGpio_SetDataDirection().

#define XGPIO_DATA2_OFFSET 0x8

Data register for 2nd channel.

#define XGPIO_DATA_OFFSET 0x0

Data register for 1st channel.

Referenced by main(), XGpio_DiscreteClear(), XGpio_DiscreteRead(), XGpio_DiscreteSet(), and XGpio_DiscreteWrite().

#define XGPIO_GIE_GINTR_ENABLE_MASK 0x80000000

Mask for Global Interrupt.

Referenced by XGpio_InterruptGlobalEnable().

#define XGPIO_GIE_OFFSET 0x11C

Glogal interrupt enable register.

Referenced by XGpio_InterruptGlobalDisable(), and XGpio_InterruptGlobalEnable().

#define XGPIO_H

by using protection macros

#define XGPIO_I_H

by using protection macros

#define XGPIO_IER_OFFSET 0x128

Interrupt enable register.

Referenced by XGpio_InterruptDisable(), XGpio_InterruptEnable(), and XGpio_InterruptGetEnabled().

#define XGpio_In32 Xil_In32

Input Operations.

#define XGPIO_IR_CH1_MASK 0x1

Mask for the 1st channel.

#define XGPIO_IR_CH2_MASK 0x2

Mask for the 2nd channel.

#define XGPIO_IR_MASK 0x3

Mask of all bits.

#define XGPIO_ISR_OFFSET 0x120

Interrupt status register.

Referenced by XGpio_InterruptClear(), and XGpio_InterruptGetStatus().

#define XGPIO_L_H

by using protection macros

#define XGpio_Out32 Xil_Out32

Output Operations.

#define XGpio_ReadReg | ( |  | BaseAddress,
|  |  | RegOffset
| ) |  | XGpio_In32((BaseAddress) + (RegOffset))

Reads a value from a GPIO register.

A 32-bit read is performed. If the GPIO core is implemented in a smaller width, only the least significant data is read from the register. The most significant data will be read as 0.

Parameters

  BaseAddress | Base address of the GPIO device.
  RegOffset | Register offset from the base to read from.

Returns
  Data read from the register.

Note
  C-style signature: u32 XGpio_ReadReg(u32 BaseAddress, u32 RegOffset)

Referenced by main(), XGpio_DiscreteClear(), XGpio_DiscreteRead(), XGpio_DiscreteSet(), XGpio_GetDataDirection(), XGpio_InterruptClear(), XGpio_InterruptDisable(), XGpio_InterruptEnable(), XGpio_InterruptGetEnabled(), and XGpio_InterruptGetStatus().

#define XGPIO_TRI2_OFFSET 0xC

I/O direction reg for 2nd channel.

#define XGPIO_TRI_OFFSET 0x4

I/O direction reg for 1st channel.

Referenced by main(), XGpio_GetDataDirection(), and XGpio_SetDataDirection().

#define XGpio_WriteReg | ( |  | BaseAddress,
|  |  | RegOffset,
|  |  | Data
| ) |  | XGpio_Out32((BaseAddress) + (RegOffset), (u32)(Data))

Performs a 32-bit write to a GPIO register.

If the GPIO core is implemented in a smaller width, only the least significant data is written.

Parameters

  BaseAddress | Base address of the GPIO device.
  RegOffset | Register offset from the base to write to.
  Data | Data written to the register.

Returns
  None.

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

Referenced by main(), XGpio_DiscreteClear(), XGpio_DiscreteSet(), XGpio_DiscreteWrite(), XGpio_InterruptClear(), XGpio_InterruptDisable(), XGpio_InterruptEnable(), XGpio_InterruptGlobalDisable(), XGpio_InterruptGlobalEnable(), and XGpio_SetDataDirection().

#define XPAR_XGPIO_NUM_INSTANCES 0

GPIO instances.

Referenced by XGpio_LookupConfig().

## Function Documentation

int XGpio_CfgInitialize | ( | XGpio * | InstancePtr,
|  | XGpio_Config * | Config,
|  | UINTPTR | EffectiveAddr
| ) |  |

Initializes the XGpio instance provided by the caller based on the given configuration data.

Nothing is done except to initialize the InstancePtr.

Parameters

  InstancePtr | Pointer to an XGpio instance. The memory the pointer references must be pre-allocated by the caller. Further calls to manipulate the driver through the XGpio API must be made with this pointer.
  Config | Reference to a structure containing information about a specific GPIO device. This function initializes an InstancePtr object for a specific device specified by the contents of Config. This function can initialize multiple instance objects with the use of multiple calls giving different Config information on each call.
  EffectiveAddr | Device base address in the virtual memory address space. The caller is responsible for keeping the address mapping from EffectiveAddr to the device physical base address unchanged once this function is invoked. Unexpected errors may occur if the address mapping changes after this function is called. If address translation is not used, use Config->BaseAddress for this parameters, passing the physical address instead.

Returns
  - XST_SUCCESS if the initialization is successful.

Note
  None.

References XGpio::BaseAddress, XGpio_Config::InterruptPresent, XGpio::InterruptPresent, XGpio_Config::IsDual, XGpio::IsDual, and XGpio::IsReady.

Referenced by XGpio_Initialize().

void XGpio_DiscreteClear | ( | XGpio * | InstancePtr,
|  | unsigned | Channel,
|  | u32 | Mask
| ) |  |

Set output discrete(s) to logic 0 for the specified GPIO channel.

Parameters

  InstancePtr | Pointer to an XGpio instance to be worked on.
  Channel | Contains the channel of the GPIO (1 or 2) to operate on.
  Mask | Set of bits that will be set to 0 in the discrete data register. All other bits in the data register are unaffected.

Returns
  None.

The hardware must be built for dual channels if this function is used with any channel other than 1. If it is not, this function will assert.

This API can only be used if the GPIO_IO ports in the IP are used for connecting to the external output ports.

References XGpio::BaseAddress, XGpio::IsDual, XGpio::IsReady, XGPIO_CHAN_OFFSET, XGPIO_DATA_OFFSET, XGpio_ReadReg, and XGpio_WriteReg.

Referenced by GpioOutputExample(), and main().

u32 XGpio_DiscreteRead | ( | XGpio * | InstancePtr,
|  | unsigned | Channel
| ) |  |

Reads state of discretes for the specified GPIO channel.

Parameters

  InstancePtr | Pointer to an XGpio instance to be worked on.
  Channel | Contains the channel of the GPIO (1 or 2) to operate on.

Returns
  Current copy of the discretes register.

Note
  The hardware must be built for dual channels if this function is used with any channel other than 1. If it is not, this function will assert.

References XGpio::BaseAddress, XGpio::IsDual, XGpio::IsReady, XGPIO_CHAN_OFFSET, XGPIO_DATA_OFFSET, and XGpio_ReadReg.

Referenced by GpioInputExample(), and XGpio_SelfTest().

void XGpio_DiscreteSet | ( | XGpio * | InstancePtr,
|  | unsigned | Channel,
|  | u32 | Mask
| ) |  |

Set output discrete(s) to logic 1 for the specified GPIO channel.

Parameters

  InstancePtr | Pointer to an XGpio instance to be worked on.
  Channel | Contains the channel of the GPIO (1 or 2) to operate on.
  Mask | Set of bits that will be set to 1 in the discrete data register. All other bits in the data register are unaffected.

Returns
  None.

Note

The hardware must be built for dual channels if this function is used with any channel other than 1. If it is not, this function will assert.

This API can only be used if the GPIO_IO ports in the IP are used for connecting to the external output ports.

References XGpio::BaseAddress, XGpio::IsDual, XGpio::IsReady, XGPIO_CHAN_OFFSET, XGPIO_DATA_OFFSET, XGpio_ReadReg, and XGpio_WriteReg.

void XGpio_DiscreteWrite | ( | XGpio * | InstancePtr,
|  | unsigned | Channel,
|  | u32 | Mask
| ) |  |

Writes to discretes register for the specified GPIO channel.

Parameters

  InstancePtr | Pointer to an XGpio instance to be worked on.
  Channel | Contains the channel of the GPIO (1 or 2) to operate on.
  Mask | Value to be written to the discretes register.

Returns
  None.

Note
  The hardware must be built for dual channels if this function is used with any channel other than 1. If it is not, this function will assert. See also XGpio_DiscreteSet() and XGpio_DiscreteClear().

References XGpio::BaseAddress, XGpio::IsDual, XGpio::IsReady, XGPIO_CHAN_OFFSET, XGPIO_DATA_OFFSET, and XGpio_WriteReg.

Referenced by GpioOutputExample(), and main().

u32 XGpio_GetDataDirection | ( | XGpio * | InstancePtr,
|  | unsigned | Channel
| ) |  |

Gets the input/output direction of all discrete signals for the specified GPIO channel.

Parameters

  InstancePtr | Pointer to an XGpio instance to be worked on.
  Channel | Contains the channel of the GPIO (1 or 2) to operate on.

Returns
  Bitmask specifying which discretes are input and which are output. Bits set to 0 are output and bits set to 1 are input.

Note

The hardware must be built for dual channels if this function is used with any channel other than 1. If it is not, this function will assert.

References XGpio::BaseAddress, XGpio::IsDual, XGpio::IsReady, XGPIO_CHAN_OFFSET, XGpio_ReadReg, and XGPIO_TRI_OFFSET.

int XGpio_Initialize | ( | XGpio * | InstancePtr,
|  | u16 | DeviceId
| ) |  |

Initializes the XGpio instance provided by the caller based on the given DeviceID.

Only InstancePtr is initialized.

Parameters

  InstancePtr | Pointer to an XGpio instance. The memory that the pointer references must be pre-allocated by the caller. Further calls to manipulate the instance/driver through the XGpio API must be made with this pointer.
  DeviceId | Unique ID of the device controlled by this XGpio instance. Passing in a device ID associates the generic XGpio instance to a specific device, as chosen by the caller or application developer.

Returns
  - XST_SUCCESS if the initialization was successful.
  - XST_DEVICE_NOT_FOUND if the device configuration data was not found for a device with the supplied device ID.

Note
  None.

References XGpio_Config::BaseAddress, XGpio::IsReady, XGpio_CfgInitialize(), and XGpio_LookupConfig().

Referenced by GpioInputExample(), GpioIntrExample(), GpioOutputExample(), and main().

void XGpio_InterruptClear | ( | XGpio * | InstancePtr,
|  | u32 | Mask
| ) |  |

Clears pending interrupts with the provided mask.

This function should be called after the software has serviced the interrupts that are pending. This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.
  Mask | Mask to clear pending interrupts. Bit positions of 1 are cleared. This mask is formed by OR'ing bits from XGPIO_IR* bits which are contained in xgpio_l.h.

Returns
  None.

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_ISR_OFFSET, XGpio_ReadReg, and XGpio_WriteReg.

Referenced by GpioHandler().

void XGpio_InterruptDisable | ( | XGpio * | InstancePtr,
|  | u32 | Mask
| ) |  |

Disable interrupts.

This function allows specific interrupts for each channel to be disabled. This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.
  Mask | Mask to disable. Bits set to 1 are disabled. This mask is formed by OR'ing bits from XGPIO_IR* bits which are contained in xgpio_l.h.

Returns
  None.

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_IER_OFFSET, XGpio_ReadReg, and XGpio_WriteReg.

Referenced by GpioDisableIntr().

void XGpio_InterruptEnable | ( | XGpio * | InstancePtr,
|  | u32 | Mask
| ) |  |

Enable interrupts.

The global interrupt must also be enabled by calling XGpio_InterruptGlobalEnable() for interrupts to occur. This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.
  Mask | Mask to enable. Bit positions of 1 are enabled. This mask is formed by OR'ing bits from XGPIO_IR* bits which are contained in xgpio_l.h.

Returns
  None.

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_IER_OFFSET, XGpio_ReadReg, and XGpio_WriteReg.

Referenced by GpioIntrExample(), and GpioSetupIntrSystem().

u32 XGpio_InterruptGetEnabled | ( | XGpio * | InstancePtr | ) |

Returns the interrupt enable mask.

This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.

Returns
  A mask of bits made from XGPIO_IR* bits which are contained in xgpio_l.h.
  None.

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_IER_OFFSET, and XGpio_ReadReg.

u32 XGpio_InterruptGetStatus | ( | XGpio * | InstancePtr | ) |

Returns the status of interrupt signals.

Any bit in the mask set to 1 indicates that the channel associated with the bit has asserted an interrupt condition. This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.

Returns
  A pointer to a mask of bits made from XGPIO_IR* bits which are contained in xgpio_l.h.

The interrupt status indicates the status of the device regardless if the interrupts from the devices have been enabled or not through XGpio_InterruptEnable().

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_ISR_OFFSET, and XGpio_ReadReg.

void XGpio_InterruptGlobalDisable | ( | XGpio * | InstancePtr | ) |

Disables the interrupt output signal.

Interrupts enabled through XGpio_InterruptEnable() will no longer be passed through until the global enable bit is set by XGpio_InterruptGlobalEnable(). This function is designed to allow all interrupts (both channels) to be disabled easily for entering a critical section. This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.

Returns
  None.

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_GIE_OFFSET, and XGpio_WriteReg.

void XGpio_InterruptGlobalEnable | ( | XGpio * | InstancePtr | ) |

Enables the interrupt output signal.

Interrupts enabled through XGpio_InterruptEnable() will not be passed through until the global enable bit is set by this function. This function is designed to allow all interrupts (both channels) to be enabled easily for exiting a critical section. This function will assert if the hardware device has not been built with interrupt capabilities.

Parameters

  InstancePtr | GPIO instance to operate on.

Returns
  None.

Note
  None.

References XGpio::BaseAddress, XGpio::InterruptPresent, XGpio::IsReady, XGPIO_GIE_GINTR_ENABLE_MASK, XGPIO_GIE_OFFSET, and XGpio_WriteReg.

Referenced by GpioIntrExample(), and GpioSetupIntrSystem().

XGpio_Config * XGpio_LookupConfig | ( | u16 | DeviceId | ) |

Lookup the device configuration based on the unique device ID.

The table ConfigTable contains the configuration info for each device in the system.

Parameters

  DeviceId | Device identifier to lookup.

Returns
  - A pointer of data type XGpio_Config which points to the device configuration if DeviceID is found.
  - NULL if DeviceID is not found.

Note
  None.

References XGpio_ConfigTable, and XPAR_XGPIO_NUM_INSTANCES.

Referenced by GpioIntrExample(), GpioOutputExample(), and XGpio_Initialize().

int XGpio_SelfTest | ( | XGpio * | InstancePtr | ) |

Runs a self-test on the driver/device.

This function performs a minimal test in which the data register is read. It only does a read without any kind of test because the hardware has been parameterized such that it may be only an input and the state of the input is unknown.

All other hardware features of the device are not guaranteed to be in the hardware since they are parameterizable.

Parameters

  InstancePtr | Pointer to the XGpio instance to be worked on. This parameter must be initialized with XGpio_Initialize().

Returns
  XST_SUCCESS always. If the GPIO device was not present in the hardware a bus error is generated. Other indicators of a bus error, such as registers in bridges or buses, may be necessary to determine if this function caused a bus error.

Note
  None.

References XGpio::IsReady, and XGpio_DiscreteRead().

void XGpio_SetDataDirection | ( | XGpio * | InstancePtr,
|  | unsigned | Channel,
|  | u32 | DirectionMask
| ) |  |

Sets the input/output direction of all discrete signals for the specified GPIO channel.

Parameters

  InstancePtr | Pointer to an XGpio instance to be worked on.
  Channel | Contains the channel of the GPIO (1 or 2) to operate on.
  DirectionMask | Bitmask specifying which discretes are input and which are output. Bits set to 0 are output and bits set to 1 are input.

Returns
  None.

Note
  The hardware must be built for dual channels if this function is used with any channel other than 1. If it is not, this function will assert.

References XGpio::BaseAddress, XGpio::IsDual, XGpio::IsReady, XGPIO_CHAN_OFFSET, XGPIO_TRI_OFFSET, and XGpio_WriteReg.

Referenced by GpioInputExample(), GpioOutputExample(), and main().

## Variable Documentation

XGpio_Config XGpio_ConfigTable[]

This table contains configuration information for each GPIO device in the system.

Referenced by XGpio_LookupConfig().

XGpio_Config XGpio_ConfigTable[]

Initial value:
= {
{
}
}

This table contains configuration information for each GPIO device in the system.

Referenced by XGpio_LookupConfig().