next up previous contents index
Next: Physical Terminals Up: Extraction Functions Previous: Menu Commands   Contents   Index

Terminals

Here, a ``terminal'' refers to a node property of an electrical device or circuit. Both masters and instances have such properties, though their internal structure differs a bit. A ``terminal_handle'' is a handle to a list of terminals, that can be passed to functions that provide information about or operate on node properties.

In the next section, we introduce ``physical terminals'', which are different objects. A physical terminal is a data structure that stores information about the physical aspects of a terminal, including its location in the layout, an object that it may be bound to, and the associated layer. If a schematic has a layout and has been associated, then each terminal (node property) has a pointer to the corresponding physical terminal, and vice-versa. Thus, in general either object can be used to reference data. In fact, in most of the functions in this section and the next, the "handle" argument can be a handle to either a node property or physical terminal.

However, cells that are electrical-only will not have physical terminals, and similarly, a layout without a corresponding schematic will lack node properties. In these cases, only the existing object type can be used.

(terminal_handle) ListTerminals()
Return a handle containing a list of the connection terminals of the current cell. These correspond to the normal contact terminals as would be defined with the subct command, as represented by node properties of the electrical cell view. On success, a handle is returned containing the terminal list. If there are no terminals defined or some other error occurs, a scalar 0 is returned.

(terminal_handle) FindTerminal(name, index, use_e, xe, ye, use_p, xp, yp)
This function will return a handle referencing a single terminal, if one can be found among the current cell contact terminals that matches the arguments. The arguments specify parameters, any of which can be ignored. The non-ignored parameters must all match.

The name can be a string that will match an applied terminal name (not a default name generated by Xic). The argument will be ignored if a scalar 0 or null or empty string is passed.

The index is the terminal order index, or -1 if the parameter is to be ignored. This is the number that is shown within the terminal box in the subct command.

If use_e is a nonzero value, the next two arguments are taken as a location in the electrical drawing. These are specified in fictitious ``microns'' which represent 1000 internal units. These are the numbers displayed in the coordinate readout area while a schematic is being edited. A location match will depend of whether the electrical cell is symbolic or not. If symbolic, a location match to any of the placement locations will count as a match (terminals can have more than one ``hot spot'' in the symbolic display). If use_e is 0, the two arguments that follow are ignored and can be any numeric values.

Similarly, if use_p is nonzero, the next two arguments represent a coordinate in the layout, given in (real) microns. If a physical terminal is placed at the given location, a match will be indicated. If use_p is zero, the two arguments that follow are ignored, and can be set to any numeric values.

The arguments should provide at least one matchable parameter. Internally, the list of terminals is scanned, and the first matching terminal found is returned, referenced by a handle. If no terminals match, a scalar zero is returned.

(terminal_handle) CreateTerminal(name, x, y, termtype)
This function will create a new terminal in the schematic of the current cell. If a name string is passed, the terminal will be given that name. If this argument is a scalar 0 or a null or empty string, the terminal will not have an assigned name but will use an internally generated name. The terminal will be placed at the location indicated by the x and y arguments, which are in fictitious ``microns'' representing 1000 database units. These are the same coordinates as displayed in the coordinate readout while a schematic is being edited.

The termtype argument can be a scalar integer or a keyword, from the list below. This will assign a type to the terminal. The type is not used by Xic, but this facility may be useful to the user.

0 input
1 output
2 inout
3 tristate
4 clock
5 outclock
6 supply
7 outsupply
8 ground

Keyword matching is case-insensitive. If the argument is not recognized, and the default ``input'' will be used.

The function returns a handle that references the new terminal on success, or a scalar zero otherwise.

(int) DestroyTerminal(thandle)
This function will destroy the terminal referenced by the passed handle, and will close the handle. This destroys the terminal, which is actually a node property of the electrical current cell, and the linkage into the physical layout, if any. If a terminal was destroyed, value one is returned, or zero on error.

(string) GetTerminalName(thandle)
Return a string containing the name of the terminal or physical terminal referenced by the handle passed as an argument. Both objects have name fields that track. However, if no name was assigned, for a terminal a default name generated by Xic is returned, whereas the return from a physical terminal will be null.

(int) SetTerminalName(thandle, name)
The first argument is a handle that references a terminal or physical terminal. The second argument is a string which gives a name to apply. It can also be a scalar 0, or if null or empty any existing assigned name will be removed. Both terminals and physical terminals have names that track, this will change both, when both objects exist. The return value is one on success, zero if error.

(int) GetTerminalType(thandle)
Return a type code for the terminal referenced by the handle passed as an argument, which can also be a handle to the corresponding physical terminal. A non-negative return represents success. The code represents the terminal type set by the user. The terminal type is not used by Xic, but is available for user applications. The defined types are listed below. The default is type 0.

0 input
1 output
2 inout
3 tristate
4 clock
5 outclock
6 supply
7 outsupply
8 ground

(int) SetTerminalType(thandle, termtype)
This function will apply a terminal type to the terminal referenced by the handle passed as the first argument, which can also be a handle to the corresponding physical terminal. The second argument is either an integer, or a string keyword, from the list below.

0 input
1 output
2 inout
3 tristate
4 clock
5 outclock
6 supply
7 outsupply
8 ground

The function returns one if the type is set successfully, zero otherwise.

(int) GetTerminalFlags(thandle)
Return the flags for the terminal referenced by the handle passed as an argument, which can also be a handle to the corresponding physical terminal. The return value is an integer with bits representing flags as listed in the table below. On error, the return value is -1.

-x1 (BYNAME)
The terminal makes connections in the schematic by name rather than by location.
0x2 (VIRTUAL)
No longer used, reserved.
0x4 (FIXED)
The physical terminal has been placed by the user, and Xic should never move it.
0x8 (SCINVIS)
The electrical terminal will not be shown in schematics.
0x10 (SYINVIS)
The electrical terminal will not be shown in the symbol.
0x100 (UNINIT)
The terminal is not initialized (internal).
0x200 (LOCSET)
The physical terminal location has not been set (internal).
0x400 (POINTS)
Set when the terminal has multiple hot-spots.
0x800 (NOPHYS)
Set if the terminal has no physical implementation, such as a temperature node. Such terminals have no physical terminals.

(int) SetTerminalFlags(thandle, flags)
This will set the first five flags listed for GetTerminalFlags in the terminal referenced by the first argument, which can also be a handle to the corresponding physical terminal. All but the five least significant bits in the flags integer are ignored. The bits that are set will set the corresponding flag in the terminal, unset bits are ignored. The value one is returned on success, zero otherwise.

(int) UnsetTerminalFlags(thandle, flags)
This will unset the first five flags listed for GetTerminalFlags in the terminal referenced by the first argument, which can also be a handle to the corresponding physical terminal. All but the five least significant bits in the flags integer are ignored. The bits that are set will unset the corresponding flag in the terminal, unset bits are ignored. The value one is returned on success, zero otherwise.

(int) GetElecTerminalLoc(thandle, index, array)
This will return terminal locations in the electrical schematic, of the terminal referenced by the first argument. This argument can also be a handle to the corresponding physical terminal. The return is dependent on whether the electrical cell is symbolic or not. Values for x and y are returned in the array, which must have size two or larger. The returned values are in fictitions ``microns'' that correspond to 1000 database units. This is the same coordinate system indicated by the coordinate readout when editing a schematic.

If the electrical cell is not symbolic, the integer index argument must be zero, and the terminal location in the schematic is returned.

If the electrical cell is symbolic, there can be arbitrarily many ``copies'' of the terminal, representing multiple ``hot spots'' where the terminal can make connections. The index argument is a 0-based index for these locations. To get all of the locations, one should call this function repeatedly while incrementing the index from zero. A return value of zero indicates that the index is out of range (or some error occurred). A return value of one indicates success, with the array containing the location.

(int) SetElecTerminalLoc(thandle, x, y)
This function specifies a location for the terminal referenced by the first argument, for use in electrical mode. The x and y are coordinates in fictitions ``microns'' which are 1000 database units. This is the same coordinate system used in the coordinate readout when editing a schematic. As for most of these functions, the first argument can also be a handle to the corresponding physical terminal.

The function behaves differently depending on whether the electrical current cell is symbolic or not. If the electrical current cell not symbolic, the passed coordinates set the terminal location within the schematic. Otherwise, in symbolic mode, there can be arbitrarily many locations set. The function will add the passed location to the list of locations for the terminal, if it is not already using the location.

The function returns one on success, zero otherwise.

(int) ClearElecTerminalLoc(thandle, x, y)
This function applies only when the electric current cell is in symbolic mode. When true, a terminal may be displayed in arbitrarily many locations, representing different possible connection points. The x and y are coordinates in fictitions ``microns'' which are 1000 database units. This is the same coordinate system used in the coordinate readout when editing a schematic. If the coordinates match a hot spot of the terminal, that location is deleted.

It is not possible to delete the last location, there is always at least one active location. Calling this function when the electrical current cell is not symbolic has no effect. The function returns one on success, zero if error.

As for most of these functions, the first argument can also be a handle to the corresponding physical terminal.


next up previous contents index
Next: Physical Terminals Up: Extraction Functions Previous: Menu Commands   Contents   Index
Stephen R. Whiteley 2024-09-29