TKGate User Documentation (Libraries)

## 9. TkGate Library Components

The TkGate distribution includes four libraries that can be loaded through the library manager. Components from these libraries can be used to add additional functionality to your designs. To use one of the libraries, open the library manager with the toolbar button and select the library you wish to load. You can then locate the module you wish to use in the module hierarchy and drag it onto the main window canvas to create an instance of it. The libraries that are available with TkGate are described in the following sections.

### 9.1 TTY

(Click to Enlarge)
Figure 9.2: TTY Device Window
The TTY library, `tty` provides a Virtual Peripheral Device (VPD) modeling a TTY device. The TTY supports input and output and models an interactive TTY terminal. You can use it in your design to provide textual interaction with the user. When you start the simulator, one TTY window will appear for each instance of a TTY VPD in your design. Your design can send characters to and receive characters from the TTY device.

Figure 9.1:
TTY Device
To use the TTY device, open the library manager with the toolbar button and load the "tty" library. You can then locate the module in the module list or module hierarchy and drag it onto the main window canvas to create an instance of it. Figure 9.1 shows the external view of the TTY instance which is defined with a symbolic module interface.

When a design containing the TTY device is simulated, it will open a window such as the one shown in Figure 9.2 (after the design has been running for a while). The text shown in this window was transmitted from the "Menagerie CPU" example. Keys pressed while the window has focus will be transmitted back to the controlling design.

Figure 9.3:
Transmit Character
To send a character to a TTY device, use the following protocol (see Figure 9.3):

- Unassert the DSR line.
- Wait for the DTR (Data Terminal Ready) line to be low.
- Drive the RD line with the ASCII code of the character to be transmitted.
- Assert the DSR (Data Set Ready) line.
- Wait for the DTR line to go high.
- Unassert the DSR line

Figure 9.4:
Receive Character
To receive a character from the TTY device, use the following protocol(see Figure 9.4):

- Unassert the CTS line.
- Wait for the RTS line to go high.
- Read the received value on the TD line.
- Assert the CTS line.
- Wait for the RTS line to go low.
- Unassert the CTS line.

Note that transmitting a character to the TTY uses "RD" and receiving a character from the TTY uses "TD" because the RD and TD are named from the perspective of the TTY device.

#### 9.1.1 Forcing TTY Characters from Simulation Scripts

You can use a simulation script to force input into a TTY device. This is done by using a special named channel "instaname`.FORCE`" where "instaname" is the fully instantiated instance name of the TTY. You can use the `$tkg$send` system task to send the string to be forced. For example, to force the input "`Hello World`" into the TTY named "`main.memory.tty0`", you could use the simulation script:

      initial
        begin
          # 10000 ;
          $tkg$send("main.memory.tty0.FORCE","Hello World");
      end

### 9.2 Drink Vending Machine

Figure 9.5: Drink Machine Device
(Click to Enlarge)
Figure 9.6: Drink Machine GUI
The drink vending machine library, "`coke`", provides a Virtual Peripheral Device (VPD) modeling a drink vending machine. The device provides input and output signals for the actuators and sensors in the virtual vending machine. You can use this device to design a vending machine circuit that controls an interactive model of a vending machine.

To use the drink machine device, open the library manager with the toolbar button and load the "`coke`" library. You can then locate the `cokemachine` module in the module hierarchy and drag it onto the main window canvas to create an instance of it. Figure 9.5 shows the external view of the cokemachine instance.

The virtual drink vending window that appears when you start the simulation is shown in Figure 9.6. It is comprised of an external view (left side) and an internal view (right side). The external view includes buttons that can be pressed to make a drink selection, a coin slot, and a bill reader.

The following interactions can be made through the drink machine GUI:

- Coins are inserted by dragging them from the user's stock of cash in the upper left corner to the coin slot.
- Bills are inserted by dragging them from the user's stock of cash in the upper left corner to the bill reader.
- Fake bills can be dragged to the bill reader to test if the control logic detects and rejects them correctly.
- Drink selections are made by pressing the drink buttons on the external view.
- Pressing the coin return lever should cause inserted coins to be returned.
- Purchased drinks appear in the margin along the bottom.

The internal view shows the columns of drinks that are available in the machine, the status of the bill scanner, the coins that have been inserted (but not used for a purchase), the coins that have been committed to a purchase, and coins that are available to make change.

The input signals on the drink machine and their function are as follows:

Signal | Description
--- | ---
DISP | Dispense - Each of the six bits dispenses a drink from one of the six columns. Drinks are dispensed on the rising edge of the signal. Only one bit should be asserted at a time, and only after ensuring the the `DISPACK` (Dispense Acknowledge) signal is low. The asserted bit should remain high until the `DISPACK` signal goes high.
ELIGHT | Empty Light - Each bit corresponds to the empty light on each of the six buttons. If a bit is asserted, then the corresponding empty light will be illuminated.
CHGQ CHGD CHGN | Dispense Change - Drop a quarter (`CHGQ`), dime (`CHGD`) or nickel (`CHGN`) from the "Change" bin. Only one of these signals (or the `CHGCOM` or `RETINS` signals) may be asserted at a time. Change is dropped on the rising edge of the signal. The signal should not be raised unless the `CHGACK` (Change Acknowledge) signals is low. The Dispense Change signal should be held high until the `CHGACK` signal goes high.
NOCHG | No Change - If asserted, illuminates the "No Change" light on the vending machine to indicate that change can not be made.
BILLIN | Bill In - Drives the bill motor to feed the inserted bill into the bill tester. Bills in the bill tester will be dropped into the "Collected" bin. The motor is activated on a positive edge of this signal. This signal should not be raised unless the `BILLACK` (Bill Acknowledge) signal is low. The Bill In signal should be held high until the `BILLACK` signal goes high.
BILLLT | Bill Light - This signal illuminates the light on the bill reader.
BILLOUT | Bill Out - Drives the bill motor to feed out the bill currently in the bill tester. The motor is activated on a positive edge of this signal. This signal should not be raised unless the `BILLACK` (Bill Acknowledge) signal is low. The Bill Out signal should be held high until the `BILLACK` signal goes high.
CHGCOM | Change Commit - This signal commits any change in the "Inserted" area to the "Collected" area. Change is committed on the rising edge of this signal. The signal should not be raised unless the `CHGACK` (Change Acknowledge) signals is low. The Dispense Change signal should be held high until the `CHGACK` signal goes high.
RETINS | Coin Return - This signal returns any change in the "Inserted" area back to the user. Change is returned on the rising edge of this signal. The signal should not be raised unless the `CHGACK` (Change Acknowledge) signals is low. The Dispense Change signal should be held high until the `CHGACK` signal goes high.
INSACK | Insert Acknowledge - This signal should be raised after seeing a positive edge on the `INSQ`, `INSD` or `INSN` signals indicating that a coin was inserted.
COST | Drink Cost - This signal drives the drink cost displayed on the external view of the vending machine. It should be the cost in nickels.
RESET | Reset - Resets the drink machine. This is an active low signal. It should be driven low to reset the machine, then kept high while using the device.

The output signals on the drink machine and their function are as follows:

Signal | Description
--- | ---
PRESS | Button Pressed - Each bit is for one of the six buttons on the drink machine and is asserted while the corresponding button is pressed.
EMPTY | Empty Sensor - Each bit corresponds to one of the drink columns and is asserted when the sensor indicates that there are no more drinks in a column.
INSQ INSD INSN | Coin Inserted - These signals indicate that a quarter (`INSQ`), dime (`INSD`) or nickel (`INSN`) have been inserted. A rising edge indicates the insertion. The controlling circuit should assert the `INSACK` signal to acknowledge the insertion.
NUMQ NUMD NUMN | Change Available - Indicates the number of quarters (`NUMQ`), dimes (`NUMD`) and nickels (`NUMN`) available for making change (up to 7). If there are more than 7 coins of a type available, then the signal will indicate 7.
BILLSNS | Bill Sense - A high value indicates that a bill is sensed in the bill insertion slot. The controlling circuit should assert `BILLIN` to feed the bill into the bill tester
BILLOK | Bill OK - A high value indicates that the bill in the bill tester is a valid bill.
CNRET | Coin Return Request - A high value indicates that the user is pressing the coin return lever.
BILLACK | Bill Acknowledge - This signal is asserted to acknowledge a `BILLIN` or `BILLOUT` signal.
CHGACK | Change Acknowledge - This signal is asserted to acknowledge a `CHGQ`, `CHGD`, `CHGN`, `CHGCOM` or `RETINS` signal.
DISPACK | Dispense Acknowledge - This signal is asserted to acknowledge a `DISP` signal.
BILLNG | Bill No Good - This signal is asserted to indicate that a fake bill is in the bill tester.

### 9.3 Timers and One-Shots

Timers and one-shots are devices that operate in real time. To use a timer or one-shot device, open the library manager with the toolbar button and load the "timer" library. You can then locate the desired device in the module list or module hierarchy and drag it onto the main window canvas to create an instance of it.

#### 9.3.1 OSCILLATOR Device

Figure 9.7:
Oscillator
The `OSCILLATOR` device provides a signal that oscillates at a set frequency in real-world time. You can use it to design circuits such as digital clocks using the LED gates. The default frequency is one hertz. To change the frequency, double click on the OSCILLATOR module to open the Gate Properties dialog box and select the "Parameters" tab. Set the "HZ" parameter to the desired period in milliseconds.

#### 9.3.2 ONESHOT Device

Figure 9.8:
One Shot
A one-shot device asserts its output a set time period after being reset by the input. The ONESHOT is triggered by an active low signal. You can connect the input to ground, to cause the ONESHOT device to assert its output after a set amount of real-world time after the simulation begins. Raising the input and lowering it again resets the one-shot. The default delay is one second. To change the time delay of the ONESHOT, double click on it to open the Gate Properties dialog box and select the "Parameters" tab. Set the "HZ" parameter to the desired delay in milliseconds.

### 9.4 TTL Devices

The TTL device library provides access to a small number of commonly used 7400 series TTL modules. To use this library, open the library manager with the toolbar button and load the "74xx" library. You can then locate the desired device in the module list or module hierarchy and drag it onto the main window canvas to create an instance of it. The supported devices are:

Device | Description
--- | ---
`7400` | Quad 2-input NAND gates
`7402` | Quad 2-input NOR gates
`7404` | Hex Inverters
`7408` | Quad 2-input AND gates
`7410` | Tri 3-input NAND gates
`7430` | 8-input NAND gate
`7432` | Quad 2-input OR gate
`7474` | Dual D-Latch, edge triggered with clear and preset
`7486` | Quad 2-input XOR gates
`74154` | 4-16 Decoder
`74157` | Quad 2-1 Mux
`74163` | 4-bit Synchronous Counter
`74175` | Quad D-Latch, edge triggered with clear

Please see standard TTL data sheets for a description of these devices.