TERMINAL Debug Console Instrument

Summary This document describes how to place and use the TERMINAL virtual instrument in an FPGA design. Core Reference CR0180 (v2.0) March 06, 2008 The TERMINAL device is a debug console instrument for use in an FPGA design. Console I/O is a common way of debugging processor systems. The TERMINAL device allows you to type text directly in its associated instrument panel, which is sent directly to the processor in your design, to be handled by the embedded software code running therein. Conversely, it allows the display of text sent from that processor. Although classed as one of Altium Designer's virtual instruments, the TERMINAL device is really a hybrid part instrument and part Wishbone-compliant slave peripheral. Whereas other instruments are configured and operated directly from a GUI, the TERMINAL device requires interaction at the code level, to initialize internal registers and to write to/read from its internal storage buffers. In terms of functionality as a peripheral, the TERMINAL device is similar to the WB_UART8 Serial Communications Port peripheral. Whereas the WB_UART8 facilitates serial communication between a processor and a remote device, the TERMINAL instrument is, in essence, the remote device as well as the facilitator of communications. The processor simply communicates directly (and serially) with the TERMINAL instrument. Features Based on, and functionally similar to, the WB_UART8 peripheral Type and send text to processor directly from instrument panel Receive text from the processor and display in instrument panel Full Duplex Ability to save text to a log file Ability to copy selected text to the clipboard Wishbone-compliant Available Devices From a schematic document, the TERMINAL device can be found in the FPGA Instruments integrated library (FPGA Instruments.IntLib), located in the \Library\Fpga folder of the installation. From an OpenBus System document, the Terminal Instrument component can be found in the Peripherals region of the OpenBus Palette panel. CR0180 (v2.0) March 06, 2008 1

Functional Description Symbol Figure 1. Symbols used for the TERMINAL instrument in both schematic (left) and OpenBus System (right). Pin Description The following pin description is for the device when used on the schematic. In an OpenBus System, although the same signals are present, the abstract nature of the system hides the pin-level Wishbone interface. Table 1. TERMINAL pin description Name Type Polarity/ Bus size Description Control Signals CLK_I I Rise External (system) clock signal RST_I I High External (system) reset Host Processor Interface Signals STB_I I High Strobe signal. When asserted, indicates the start of a valid Wishbone data transfer cycle CYC_I I High Cycle signal. When asserted, indicates the start of a valid Wishbone cycle ACK_O O High Standard Wishbone device acknowledgement signal. When this signal goes high, the TERMINAL (Wishbone Slave) has finished execution of the requested action and the current bus cycle is terminated ADR_I I 4 Address bus, used to select an internal register of the device for writing to/reading from DAT_O O 8 Data to be sent to host processor DAT_I I 8 Data received from host processor WE_I I Level Write enable signal. Used to indicate whether the current local bus cycle is a Read or Write cycle: 0 = Read 1 = Write 2 CR0180 (v2.0) March 06, 2008

Name Type Polarity/ Bus size Description INT_O O 2/High Interrupt output lines. Two interrupts are sent to the connected processor on this 2-bit bus: bit 0 = Goes High if the txempty bit in the Interrupt Control register (INTCTRL.1) is set and the txempty bit in the Status register (STATUS.1) becomes set bit 1 = Goes High if the rxnempty bit in the Interrupt Control register (INTCTRL.5) is set and the rxnempty bit in the Status register (STATUS.5) becomes set. Hardware Description Block Diagram TERMINAL Debug Console Instrument CLK_I RST_I DAT_I[7..0] DAT_O[7..0] ADR_I[3..0] SBUF TRANSMIT FIFO Transmit Shift CYC_I STB_I WE_I ACK_O SBUF Receive Shift RECEIVE FIFO INT_O[1..0] STATUS INTCTRL INTSTATUS Figure 2. TERMINAL block diagram Internal Registers The following sections detail the internal registers for the TERMINAL instrument. Under the bonnet, the device uses the same register addresses as those for the WB_UART8. However, only the registers and bits pertinent to the function of the TERMINAL instrument are detailed as part of this document. CR0180 (v2.0) March 06, 2008 3

Status Register (STATUS) Address: 0100b Access: Read-only Value after Reset: 00001010b This 8-bit register is used to determine the current state of the TERMINAL instrument. Table 2. The STATUS register MSB LSB rxfull - rxnempty - txshempty - txempty txfull Table 3. STATUS register bit functions Bit Symbol Function STATUS.7 rxfull Receiver Full flag. Taken High if the Receive Buffer is full. STATUS.6 - Not used. Returns '0' when read. STATUS.5 rxnempty Receiver Not Empty flag. Taken High if the Receive Buffer is not empty. STATUS.4 - Not used. Returns '0' when read. STATUS.3 txshempty Transmitter Shift Register Empty flag. Taken High if the Transmitter shift register is empty. STATUS.2 - Not used. Returns '0' when read. STATUS.1 txempty Transmitter Empty flag. Taken High if the Transmit Buffer is empty. STATUS.0 txfull Transmitter Full. Taken High if the Transmit Buffer is full. Interrupt Control Register (INTCTRL) Address: 0101b Access: Read/Write Value after Reset: 00000000b This 8-bit register is used to enable interrupt generation for each of the corresponding bits in the STATUS register. Provided bit INTCTRL.n is High, an interrupt will be generated when the corresponding bit STATUS.n goes High. Table 4. The INTCTRL register MSB LSB - - rxnempty - - - txempty - Table 5. INTCTRL register bit functions Bit Symbol Function INTCTRL.7 - Not used. INTCTRL.6 - Not used. INTCTRL.5 rxnempty Enables interrupt generation for Receiver Not Empty flag (STATUS.5). INTCTRL.4 - Not used. INTCTRL.3 - Not used. INTCTRL.2 - Not used. INTCTRL.1 txempty Enables interrupt generation for Transmitter Empty flag (STATUS.1). INTCTRL.0 - Not used. 4 CR0180 (v2.0) March 06, 2008

Interrupt Status Register (INTSTATUS) Address: 0110b Access: Read/Write This is not actually a register in the true sense of the word, but rather is a single address with which to effectively write to the Status register to clear flags after a generated interrupt: After a transmitter interrupt, whereby the txempty and txshempty bits of the Status register (STATUS.1 and STATUS.3) are taken High, writing to the INTSTATUS address with DAT_I(1) = '1' will clear both the txempty and the txshempty flags in the Status register. After a receiver interrupt, whereby the rxnempty and rxfull bits of the Status register (STATUS.5 and STATUS.7) are taken High, writing to the INTSTATUS address with DAT_I(5) = '1' will clear both the rxnempty and the rxfull flags in the Status register. Performing a Wishbone Read from the INTSTATUS address retrieves data directly from the Status register. Serial Data Buffer Register (SBUF) Address: 0111b Access: Read/Write This is not actually a register in the true sense of the word, but rather is a single address that is used to access the Transmit and Receive Buffers. Performing a Wishbone Write to the SBUF address loads data directly into the Transmit Buffer. If the Buffer is full, transmission may stop and the buffer content is overwritten. Performing a Wishbone Read from the SBUF address retrieves data directly from the Receive Buffer. If no bytes are available in the Receive Buffer, the returned byte is invalid. Otherwise, the retrieved byte is removed from the buffer, effectively freeing up space. Interrupts The TERMINAL instrument generates two interrupts one each catering for the transmit and receive sections of the device. In terms of transmission, an interrupt will be generated if the Transmit Buffer becomes empty flagging to the processor that there is no data in the buffer to be transmitted for display in the instrument's panel. In terms of reception, an interrupt will be generated if the Receive Buffer is not empty flagging to the processor that there is data in the buffer that it needs to read. This means that text has been entered into the instrument's panel, but not all data has been read by the processor. Transmit Interrupt To enable this interrupt, the txempty bit of the Interrupt Control register (INTCTRL.1) must be set. When the Transmit Buffer becomes empty, the txempty flag in the Status register will be set and the external interrupt line to the processor INT_O(0) will be taken High. The txshempty bit in the Status register (STATUS.3) is also set, although the generation of the interrupt is not dependent on this bit. This interrupt state is cleared by writing "00000010" to the address for the Interrupt Status register. The result of this operation will be to clear the txempty and txshempty bits in the Status register. Receive Interrupt To enable this interrupt, the rxnempty bit of the Interrupt Control register (INTCTRL.5) must be set. When the Receive Buffer remains not empty, the rxnempty flag in the Status register will be set and the external interrupt line to the processor INT_O(1) will be taken High. The rxfull bit in the Status register (STATUS.7) is also set, although the generation of the interrupt is not dependent on this bit. This interrupt state is cleared by writing "00100000" to the address for the Interrupt Status register. The result of this operation will be to clear the rxnempty and rxfull bits in the Status register. CR0180 (v2.0) March 06, 2008 5

Placing a TERMINAL Instrument in a Design How the TERMINAL instrument is placed and wired within an FPGA design depends on the method used to build that design. The main processor-based system can be either defined purely on the schematic sheet, or it can be contained as a separate OpenBus System, which is then referenced from the top-level schematic. The following sections take a look at using the TERMINAL device in both of these design arenas. Design using a Schematic only Figure 3 illustrates how a TERMINAL device can be wired into a schematic-based design that uses a 32-bit processor in this case a TSK3000A. A configurable Wishbone Interconnect device (WB_INTERCON) is used to simplify connection and also handle the address mapping taking the 24-bit address line from the processor and mapping it to the 4-bit address line used to drive the TERMINAL. Figure 3. Example interfacing between a 32-bit processor (TSK3000A) and a TERMINAL instrument. Internal TERMINAL registers are accessed directly by adding the 4-bit address for the required register to the 24-bit base address of the TERMINAL device. This base address is specified as part of the peripheral s definition when adding it as a slave to the Wishbone Interconnect. For example, if the base address entered for the device is 100000h (mapping it to address FF10_0000h in the processor s address space), and you want to write to the Interrupt Control register (INTCTRL) with binary address 0101 (or 5h), the value entered on the processor s 24-bit IO_ADR_O line would be: 100000h + 5h = 100005h For further information on the Wishbone Interconnect, refer to the CR0150 WB_INTERCON Configurable Wishbone Interconnect core reference. For further information on the TSK3000A processor, refer to the CR0121 TSK3000A 32-bit RISC Processor core reference. Similar references can be found for other 32-bit processors supported by Altium Designer, by using the lower section of the 6 CR0180 (v2.0) March 06, 2008

Knowledge Center panel and navigating to the Documentation Library» Embedded Processors and Software Development» FPGA Based and Discrete Processors section. Design Featuring an OpenBus System Figure 4 illustrates identical use of the TERMINAL instrument within a design where the main processor system has been defined as an OpenBus System. The Terminal Instrument component (as it is referred to in the OpenBus System world) is connected to the TSK3000A processor through an Interconnect component. The OpenBus System environment is a much more abstract and intuitive place to create a design, where the interfaces are reduced to single ports and connection is made courtesy of single links. Much of the configuration is handled for you there is no addressing mode to specify, no data width to enter the Terminal Console Instrument component is automatically added as a slave to the Interconnect component by virtue of its link. The Interconnect contains information regarding the device's address bus size and a default decoder address width. All that is really needed is specification of the peripheral's base address where in the TSK3000A's address space it is to be mapped. Figure 4. Example interfacing between a 32-bit processor (TSK3000A) and a Terminal Console Instrument, as part of an OpenBus System. An OpenBus System is defined on an OpenBus System Document (*.OpenBus). This document is referenced from the FPGA design's top-level schematic sheet through a sheet symbol. Figure 5 illustrates the interface circuitry between the external interfaces of I/O peripherals in the OpenBus System which arrive on the top sheet as sheet entries on the parent sheet symbol and the physical pins of the target FPGA device. Note that as the Terminal Console Instrument has no external interface, there are no corresponding sheet entries associated with it on the sheet symbol. Figure 5. Wiring the OpenBus System-based I/O peripherals to the physical pins of the FPGA device. CR0180 (v2.0) March 06, 2008 7

For further information on the Interconnect component, refer to the document TR0170 OpenBus Interconnect Component Reference. For more information on the concepts and workings of the OpenBus System, refer to the article AR0144 Streamlining Processor-based FPGA design with the OpenBus System. For an example OpenBus System-based FPGA design featuring a TERMINAL instrument, refer to the example project: \Examples\NB1 Examples\OpenBus DSF PS2 Terminal\DSF_PS2_UART.PrjFpg. Enabling the Soft Devices JTAG Chain Communications from the Altium Designer software environment to embedded processors and virtual instruments in an FPGA design, is carried out over a JTAG communications link. This is referred to on the NanoBoard as the Soft JTAG (or Nexus) chain. Within Altium Designer, such devices included in the chain are presented in the Devices view as part of the Soft Devices chain. The Soft JTAG chain signals (NEXUS_TMS, NEXUS_TCK, NEXUS_TDI and NEXUS_TDO) are derived in the NanoBoard's NanoTalk Controller (Xilinx Spartan-3). As part of the communications chain, these signals are wired to four pins of the daughter board FPGA. To interface to these pins, you need to place the NEXUS_JTAG_CONNECTOR design interface component (Figure 6). This can be found in the FPGA NB2DSK01 Port-Plugin integrated library (\Library\Fpga\FPGA NB2DSK01 Port-Plugin.IntLib). This component 'brings' the Soft JTAG chain into the design. In order to wire all relevant Nexus-enabled devices (processors, virtual instruments) into this chain, you need to also place a NEXUS_JTAG_PORT component (Figure 7), and connect this directly to the NEXUS_JTAG_CONNECTOR (Figure 8). This component can be found in the FPGA Generic integrated library (\Library\Fpga\FPGA Generic.IntLib). The presence of the NEXUS_JTAG_PORT component instructs the software to wire all components that possess the parameter NEXUS_JTAG_DEVICE=True into the Soft JTAG chain. Figure 6. Nexus JTAG Connector. Figure 7. Nexus JTAG Port. Figure 8. Connecting JTAG devices into the Soft JTAG chain. 8 CR0180 (v2.0) March 06, 2008

Host to Controller Communications Communications between a 32-bit host processor and the TERMINAL instrument are carried out over a standard Wishbone bus interface. The following sections detail the communication cycles involved between host and peripheral device for writing to/reading from the internal registers. Writing to an Internal Register Data is written from the host processor to an internal register in the TERMINAL instrument, in accordance with the standard Wishbone data transfer handshaking protocol. The write operation occurs on the rising edge of the CLK_I signal and can be summarized as follows: The host presents the required 24-bit address based on the register to be written on its IO_ADR_O output and valid data on its IO_DAT_O output. It then asserts its IO_WE_O signal, to specify a write cycle The TERMINAL instrument receives the 4-bit address on its ADR_I input and, identifying the addressed register, prepares to receive data into that register The host asserts its IO_STB_O and IO_CYC_O outputs, indicating that the transfer is to begin. The TERMINAL instrument, which monitors its STB_I and CYC_I inputs on each rising edge of the CLK_I signal, reacts to this assertion by latching the data appearing at its DAT_I input into the target register and asserting its ACK_O signal to indicate to the host that the data has been received The host, which monitors its IO_ACK_I input on each rising edge of the CLK_I signal, responds by negating the IO_STB_O and IO_CYC_O signals. At the same time, the TERMINAL instrument negates the ACK_O signal and the data transfer cycle is naturally terminated. Table 6 summarizes how the byte of data from the host processor is used when writing to the TERMINAL instrument's internal register addresses. Table 6. Values written to internal registers during a write. Writing to... INTCTRL INTSTATUS SBUF Results in... DAT_I(7..0) loaded into the INTCTRL register If DAT_I(5) = '1': STATUS.5 is cleared to '0' STATUS.7 is cleared to '0' If DAT_I(1) = '1': STATUS.1 is cleared to '0' STATUS.3 is cleared to '0' DAT_I(7..0) loaded into the Transmit Buffer Reading from an Internal Register Data is read from an internal register in accordance with the standard Wishbone data transfer handshaking protocol. The read operation, which occurs on the rising edge of the CLK_I signal, can be summarized as follows: The host presents the required 24-bit address based on the register to be read on its IO_ADR_O output. It then negates its IO_WE_O signal, to specify a read cycle The TERMINAL instrument receives the 4-bit address on its ADR_I input and, identifying the addressed register, prepares to transmit data from the selected register The host asserts its IO_STB_O and IO_CYC_O outputs, indicating that the transfer is to begin. The TERMINAL instrument, which monitors its STB_I and CYC_I inputs on each rising edge of the CLK_I signal, reacts to this assertion by presenting the valid data on its DAT_O output and asserting its ACK_O signal to indicate to the host that valid data is present The host, which monitors its IO_ACK_I input on each rising edge of the CLK_I signal, responds by latching the data appearing at its IO_DAT_I input and negating the IO_STB_O and IO_CYC_O signals. At the same time, the TERMINAL instrument negates the ACK_O signal and the data transfer cycle is naturally terminated. Table 7 summarizes the 'make-up' of the byte of data that is read back from each register. CR0180 (v2.0) March 06, 2008 9

Table 7. Values read from internal registers during a read. Reading from... STATUS Presents (to host processor)... 8-bit value currently in the STATUS register INTCTRL "00000000" INTSTATUS SBUF 8-bit value currently in the STATUS register Next byte of data in the Receive Buffer Operating the TERMINAL Instrument Once the design is processed and downloaded into the physical FPGA device, the instrument can be used. Displays and controls for the instrument can be found on the device's associated instrument panel. This panel enables you to effectively use the instrument in your design. The following sections detail initialization of the instrument, how the associated instrument panel is accessed, and subsequent use of the panel to send and receive text to/from the processor. Initialization After an external reset, you will need to initialize the TERMINAL instrument. This is a very simple procedure that involves: Writing to the Interrupt Control register and setting the txempty (INTCTRL.1) and rxnempty (INTCTRL.5) bits, thereby enabling interrupts. Writing 22h to the address for the Interrupt Status register, to ensure that the interrupt-generating txempty and rxnempty flags in the Status register (STATUS.1 and STATUS.5 respectively) are cleared. The txshempty flag (STATUS.3) which is initially set to '1' on reset will also be cleared by this write. Accessing the TERMINAL Device's Instrument Panel The host computer is connected to the target TERMINAL instrument using the IEEE 1149.1 (JTAG) standard interface. This is the physical interface, providing connection to physical pins of the FPGA device in which the instrument has been embedded. The Nexus 5001 standard is used as the protocol for communications between the host and all devices that are debug-enabled with respect to this protocol. This includes the TERMINAL instrument, as well as other Nexus-compliant devices such as debugenabled processors, frequency generators, logic analyzers, counters and digital I/O modules. All such devices are connected in a chain the Soft Devices chain which is determined when the design has been implemented within the target FPGA device and presents within the Devices view (Figure 9). It is not a physical chain, in the sense that you can see no external wiring the connections required between the Nexus-enabled devices are made internal to the FPGA itself. Figure 9. Nexus-enabled devices appearing in the Soft Devices chain. The controls for a TERMINAL instrument used in a design can be accessed from the Devices view. Simply double-click on the icon representing the TERMINAL instrument whose controls you wish to access, in the Soft Devices region of the view. The Instrument Rack Soft Devices panel will appear, with the chosen instrument added to the rack (Figure 10). 10 CR0180 (v2.0) March 06, 2008

Figure 10. Accessing the TERMINAL module's instrument panel. Note: Each TERMINAL instrument that you have included in the design will appear, when double-clicked, as an instrument in the rack (along with any other Nexus-enabled devices). Sending and Receiving Text After an external reset, the instrument is effectively ready for use straight away. See the previous section on Initialization for setting up the instrument's interrupt generation capabilities. If data is available in the Transmit Buffer (sent from the processor), the instrument will start sending it, via the Soft JTAG Chain, for display in the instrument panel. Figure 11 illustrates an example of displayed text. The text itself was typed on a remote PS/2 keyboard attached to a NanoBoard, the design circuitry of which is reflected in Figure 3 previously. The processor, having obtained the textual data using an intermediate PS2_W Controller, has then sent out this text to the connected TERMINAL instrument. Figure 11. Example text sent from the processor and displayed in the TERMINAL module's instrument panel. If text is typed directly into the instrument panel, the Receiver will automatically start receiving it, via the Soft JTAG Chain, to be subsequently read by the processor. Figure 12 illustrates an example of locally-typed text, destined to be read and processed by the embedded software code running on the target processor. Figure 12. Example text entered directly into the TERMINAL module's instrument panel. CR0180 (v2.0) March 06, 2008 11

Text can be sent and received concurrently (i.e. the TERMINAL instrument is Full Duplex by nature). Note: Unlike the WB_UART8 device, the Baud Rate is not user definable for the TERMINAL instrument. Instead, the instrument operates at maximum possible speed, dependent on the transmission medium used for the JTAG link between the NanoBoard and the PC. This operational speed can vary considerably. For example, the maximum Baud Rate using a USB connection can be in the range 2000 2200 Baud. For a parallel port connection, this can be as high as 7000 Baud. For an example of software routines related to the use of the TERMINAL instrument, refer to the file main.c in the embedded project (PS2 UART.PrjEmb) associated with the following example FPGA design: \Examples\NB1 Examples\OpenBus DSF PS2 Terminal\DSF_PS2_UART.PrjFpg. Where calls are made to functions used to initialize the instrument, send and receive data, handle interrupts and so on, these functions can be found in the file llpi_wb_terminal.c. This file can be found in the \System\Tasking\dsf\llpi\src folder of the installation. Additional Panel Functions The instrument panel for the TERMINAL device provides several additional functions related to the text currently displayed. These features are summarized in the following sections. Copying Text The panel allows you to copy text to the clipboard. To do so, simply drag to highlight the text you wish to copy. A menu will appear, giving you the option to copy to the clipboard (Figure 13). Figure 13. Copying highlighted text to the clipboard. Saving Text Should you wish to save the currently displayed text, you can do so. The panel enables you to save its content in a log file. Simply click on the Save To File button at the bottom left of the panel. The Choose File To Save Terminal Log dialog will appear, from where you can nominate where, and under what name, the resulting log file (*.log) is saved. Figure 14 illustrates an example generated log file. Figure 14. Saving all text to a designated log file. Clearing Text To clear all current text from the panel, simply click on the Clear button at the bottom left of the panel. All text will be cleared and the text cursor will be repositioned at the top left corner of the text window. 12 CR0180 (v2.0) March 06, 2008

Revision History Date Version No. Revision 18-Oct-2007 1.0 Initial release 06-Mar-2008 2.0 Updated for Altium Designer Summer 08 Software, hardware, documentation and related materials: Copyright 2008 Altium Limited. All rights reserved. You are permitted to print this document provided that (1) the use of such is for personal use only and will not be copied or posted on any network computer or broadcast in any media, and (2) no modifications of the document is made. Unauthorized duplication, in whole or part, of this document by any means, mechanical or electronic, including translation into another language, except for brief excerpts in published reviews, is prohibited without the express written permission of Altium Limited. Unauthorized duplication of this work may also be prohibited by local statute. Violators may be subject to both criminal and civil penalties, including fines and/or imprisonment. Altium, Altium Designer, Board Insight, Design Explorer, DXP, LiveDesign, NanoBoard, NanoTalk, P-CAD, SimCode, Situs, TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries. All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the same are claimed. CR0180 (v2.0) March 06, 2008 13