 |
iomodule
Vitis Drivers API Documentation
|
|
iomodule
Vitis Drivers API Documentation
|
The Xilinx IO Module driver component. This component supports the IO Module. The IO Module provides:
Universal Asynchronous Receiver Transmitter (UART): This UART is a minimal hardware implementation with minimal features. Most of the features, including parity, and number of data bits are only configurable when the hardware device is built, rather than at run time by software. The UART has an internal baud rate generator that is clocked at a specified input clock frequency. The baud rate can either be fixed, or programmable. Not all programmed baud rates can be generated from some clock frequencies. The requested baud rate is checked using the provided clock for the system, and checked against the acceptable error range. An error may be returned from some functions indicating the baud rate was in error because it could not be generated.
The device has support for interrupts: a transmit interrupt, a receive interrupt, and an error interrupt. The interrupts are individually configurable when the hardware device is built.
The driver defaults to no interrupts at initialization such that interrupts must be enabled if desired. An interrupt is generated when the transmitter transitions from having data to being empty, when any data is contained in the receive register, or when an error occurs in received data.
In order to use interrupts, it's necessary for the user to connect the driver interrupt handler, XIOModule_InterruptHandler, to the interrupt system of the application. This function does not save and restore the processor context such that the user must provide it. Send and receive handlers may be set for the driver such that the handlers are called when transmit and receive interrupts occur. The handlers are called from interrupt context and are designed to allow application specific processing to be performed.
The functions, XIOModule_Send and XIOModule_Recv, are provided in the driver to allow data to be sent and received. They are designed to be used in polled or interrupt modes.
The driver provides a status for each received byte indicating any parity frame or overrun error. The driver provides statistics which allow visibility into these errors.
Fixed Interval Timer (FIT): The fixed interval timer supports the following features:
The timer has a hardware programmed time period, which can be configured to cause a periodic interrupt. The driver only provides the ability to handle such interrupts.
Programmable Interval Timer (PIT): The programmable interval timer supports the following features:
The timer operates in compare mode. The timer always counts down.
Compare mode is typically used for creating a single time period or multiple repeating time periods in the auto reload mode, such as a periodic interrupt. When started, the timer loads an initial value, referred to as the load value, into the timer and starts counting down. The timer expires when it rolls under. An external Output signal may be configured such that a pulse is generated with this signal when it rolls under.
The timer can be configured to cause an interrupt when the count reaches zero. An external output is also toggled when the count reaches zero.
Interrupts
It is the responsibility of the application to connect the interrupt handler of the timer to the interrupt source. The interrupt handler function, XIOModule_InterruptHandler, is visible such that the user can connect it to the interrupt source. Note that this interrupt handler does not provide interrupt context save and restore processing, the user must perform this processing.
The driver services interrupts and passes timeouts to the upper layer software through callback functions. The upper layer software must register its callback functions during initialization. The driver requires callback functions for timers.
General Purpose Output (GPO): The GPO has support for up to 32 I/O discrete outputs for each channel (128 bits total).
IO Bus (IO): The IO Bus provides a generic mechanism to extend the IO Module functionality by providing a memory mapped IO area. Reading and writing of byte, halfword and word data is provided.
General Purpose Input (GPI): The GPI has support for up to 32 I/O discrete outputs for each channel (128 bits total). An interrupt can be generated when any bit in a GPI changes.
Interrupt controller (INTC): The interrupt controller driver uses the idea of priority for the various handlers. Priority is an integer within the range of 0 and 31 inclusive with 0 being the highest priority interrupt source.
The Xilinx interrupt controller supports the following features:
The acknowledgement of the interrupt within the interrupt controller is selectable, either prior to the device's handler being called or after the handler is called. This is necessary to support interrupt signal inputs which are either edge or level signals. Edge driven interrupt signals require that the interrupt is acknowledged prior to the interrupt being serviced in order to prevent the loss of interrupts which are occurring extremely close together. A level driven interrupt input signal requires the interrupt to acknowledged after servicing the interrupt to ensure that the interrupt only generates a single interrupt condition.
Details about connecting the interrupt handler of the driver are contained in the source file specific to interrupt processing, xiomodule_intr.c.
This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.
Interrupt Vector Tables
The interrupt vector table for each interrupt controller device is declared statically in xiomodule_g.c within the configuration data for each instance. The device ID of the interrupt controller device is used by the driver as a direct index into the configuration data table - to retrieve the vector table for an instance of the interrupt controller. The user should populate the vector table with handlers and callbacks at run-time using the XIOModule_Connect() and XIOModule_Disconnect() functions.
Each vector table entry corresponds to a device that can generate an interrupt. Each entry contains an interrupt handler function and an argument to be passed to the handler when an interrupt occurs. The tools default this argument to the base address of the interrupting device. Note that the device driver interrupt handlers given in this file do not take a base address as an argument, but instead take a pointer to the driver instance. This means that although the table is created statically, the user must still use XIOModule_Connect() when the interrupt handler takes an argument other than the base address. This is only to say that the existence of the static vector tables should not mislead the user into thinking they no longer need to register/connect interrupt handlers with this driver.
With fast interrupts enabled, the XIOModule_ConnectFastHandler() function should be used instead of XIOModule_Connect(). Note that the function pointer parameter Handler, must be a declared with the fast_interrupt attribute:
void Handler() attribute((fast_interrupt));
The routine defined by XIOModule_Connect() can be used by setting normal interrupt mode, using XIOModule_SetNormalIntrMode().
This API utilizes 32 bit I/O to the registers. With less than 32 bits, the unused bits from registers are read as zero and written as don't cares.
MODIFICATION HISTORY:
Ver Who Date Changes
1.00a sa 07/15/11 First release 1.01a sa 04/10/12 Updated with fast interrupt 1.02a sa 07/25/12 Updated with GPI interrupts and programmable baudrate 2.0 adk 19/12/13 Updated as per the New Tcl API's 2.1 bss 05/02/14 Added PitMask in XIOModule_Config.(CR #794167) 2.2 nsk 07/21/15 Updated iomodule_define_vector_table by removing absoluted hsi commands like xget_handle.CR#865544. modified generate proc to get canonical definitions in xparameters.h 2.2 nsk 08/06/15 Updated XIOModule_Uart_InterruptHandler function in xiomodule_uart_intr.c file to read Status register instead of reading Interrupt Pending register. (CR #862715). 2.2 nsk 08/07/15 Updated iomodule_define_vector_table in iomodule.tcl to handle External vector interrupts.(CR #871572) 2.2 nsk 08/19/15 Modified iomodule_define_vector_table in iomodule.tcl to handle,if iomodule doesn't have interrupts enabled (CR #876507). 2.2 nsk 09/02/15 Modified iomodule_define_vector_table in iomodule.tcl when no external interrupts are used.(CR #878782) 2.3 nsk 11/05/15 Updated xdefine_canonical_xpars in iomodule.tcl to Generate canonical definitions, whose canonical name is not the same as hardware instance name. (CR #876604) 2.4 ms 01/23/17 Added xil_printf statement in main function for all examples to ensure that "Successfully ran" and "Failed" strings are available in all examples. This is a fix for CR-965028. ms 03/17/17 Added readme.txt file in examples folder for doxygen generation. 2.5 ms 04/18/17 Modified tcl file to add suffix U for all macros definitions of iomodule in xparameters.h ms 08/07/17 Fixed compilation warnings in xiomodule.c, xiomodule_l.c, xiomodule_uart.c 2.7 sa 11/09/18 Updated XIOModule_Config to support 64 bit base addresses. 2.9 mus 08/31/20 Updated makefile to support parallel make and incremental builds. It would help to reduce compilation time. 2.10 nsk 12/14/20 Updated the tcl to not to use the instance names. 2.11 mus 05/07/21 Fixed warnings reported by doxygen tool. It fixes CR#1088640. 2.12 sk 06/08/21 Fix coverity warnings. 2.12 sk 06/08/21 Fix misra_c_8_2 coverity warning. 2.13 sk 10/04/21 Update functions return type to fix misra-c violation. 2.13 sk 10/30/21 Add function declaration for XIOModule_Intc_SelfTest. 2.14 dp 08/08/22 Fix doxygen warnings. 2.14 dp 08/30/22 Add missing declaration for Get and Clear Stats. 2.15 ml 02/27/23 converted signed macros into unsigned macros to fix misra-c violations. 2.15 adk 04/14/23 Added support for system device-tree flow.