Introduction

This Document describes the "Source Position API" - this is an extension to the Database API and bases on the zdb sub-command $db spos.

Spos data is usually created by a parser, but it can also be created through the API with load -spos, spos add and spos addline.

Overview

The spos data defines source file positions for database objects (if the parser provides them). Each database object (e.g. a net, instance, pin, etc) has zero or more associated spos data entries. Each spos entry consist of a filename and a begin and end file position. Both ways are supported, (a) finding the file positions of a database object as well as (b) finding the object at a certain file position. Most commands which use a file name string to identify a specific file can use an index prefixed by -idx. Command which return a file name or set a file name string value have a -idx option to set index values instead.

The commands are:

  • $db load -spos $file $begin $end

  • $db spos pick ?-acceptCallback cmd? (-idx $idx)|$fname $filepos

  • $db spos picklist ?-limit $limit? (-idx $idx)|$fname $filepos

  • $db spos foreach $oid ?-idx? fname begin end $body

  • $db spos foreach -all|-grey|.. (-idx $idx)|$fname oid begin end $body

  • $db spos foreachfiltered (-idx $idx)|$fname $first $last $oidList begin end $body

  • $db spos foreachrange ?-acceptCallback cmd? ?-uniq $cnt? ?-column $b $e? ?-idx? $fname $first $last oid begin end $body

  • $db spos foreachfile ?-idx? fname modtime $body

  • $db spos exists $fname

  • $db spos mtime (-idx $idx)|$fname

  • $db spos maxcolumn (-idx $idx)|$fname

  • $db spos filetype (-idx $idx)|$fname

  • $db spos neighbor $oid (-idx $idx)|$fname $pos prevFname prevBegin prevEnd nextFname nextBegin nextEnd

  • $db spos add ($oid|-grey|-comment) $file $begin $end

  • $db spos addfile ?-type $t? $file

  • $db spos addline $file $lineno ?$filepos?

  • $db spos lineno ?-no|-beg|-end? (-idx $idx)|$fname $filepos

  • $db spos filepos ?-beg|-end? (-idx $idx)|$fname $lineno

  • $db spos delete $oid

  • $db spos clone $src $dest ?$limit?

  • $db spos fnamebase ?$fname?

  • $db spos setfname (-idx $idx)|$fname ?-short? $newfname

  • $db spos getfname (-idx $idx)|$fname ?-short?

The $oid and $oidList arguments refer to database objects (OIDs).

The $file and fname arguments refer to file names.

The modtime argument refers to the file modification time stamp.

The $lineno argument refers to the line number within a file — starting at 1.

The $begin, $end, $filepos, $first and $last as well as begin and end arguments refer to byte positions within a file (seek position) — starting at 0. The $begin, $first and begin point to the first byte of a range, but $end, $last and end point to one byte after the range (i.e. end - begin is the size of a range).

Line Numbers

The spos data additionally maintains a mapping from line numbers to byte positions and vice versa. Line numbers start at 1, byte positions start at 0.

spos add

$db spos add $oid (-idx $idx)|$fname $begin $end

Appends a new spos entry to the given object.

spos addfile

$db spos addfile ?-type $t? $file

Creates a new file entry with the filename $file. Returns a unique index which can be used in -sposx options of the $db load …​ commands.

spos addline

$db spos addline $file $lineno ?$filepos?

Creates a new line-number entry that maps the given $lineno to the given file byte position $filepos — that must be the end-of-line position, in other words, $filepos must point to a newline (\n) character. The file $file must already exist; the $lineno should be increased for each call. If it is not in sequence or some line numbers are skipped, the missing lines are calculated internally on demand. If $lineno's value is all the whole file is scanned for end-of-line positions. The size of the file should be stored by using end as $lineno's value.

spos lineno

$db spos lineno ?-no|-beg|-end? (-idx $idx)|$fname $filepos

Returns a triplet with line number, the begin position and the end position of the line. If $filepos is out of range it generates an error. The begin file position is the first character in the line. The end file position is one character after the end of the line — that is the first character of the next line. If $filepos is end the triplet of the last line is returned. If one of the convenience options is used, only one value instead of a triplet is returned.

Here are some examples for different files:

command returns comment

$db spos lineno file 0

error

for an empty file

1 0 1

for a file containing only "\n"

1 0 1

for a file containing only "\n\n\n"

1 0 3

for a file containing only "AB\n\n\n"

$db spos lineno file 2

1 0 3

for a file containing only "AB\n\n\n"

$db spos lineno file 3

2 3 4

for a file containing only "AB\n\n\n"

$db spos lineno file 4

3 4 5

for a file containing only "AB\n\n\n"

$db spos lineno file end

3 4 5

for a file containing only "AB\n\n\n"

$db spos lineno file 5

3 4 5

for a file containing only "AB\n\n\n"

$db spos lineno file 6

error

for a file containing only "AB\n\n\n"

spos filepos

$db spos filepos ?-beg|-end? (-idx $idx)|$fname $lineno

Returns a pair with the begin position and the end position of the given line. If $lineno is out of range it generates an error. If $lineno is end the file position of the last line is returned. The begin file position is the first character in the line. The end file position is one character after the end of the line — that is the first character of the next line. If one of the convenience options is used, only one value instead of a pair is returned.

Here are some examples for different files:

command returns comment

$db spos filepos file 1

error

for an empty file

0 1

for a file containing only "\n\n\n"

Object Positions

The spos data maintains a mapping from object-ids to source file positions (defined by filename, begin and end) and vice versa. The file positions "begin" and "end" are byte positions in the file (number of bytes from the begin of the file).

spos pick

$db spos pick ?-acceptCallback $cmd? (-idx $idx)|$fname $filepos

This command results the OID of the object that maps to the source file range at the given $filepos (begin <= $filepos < end). If multiple objects' source file position ranges match with the given $filepos, then the smallest range (smallest end-begin) has priority and is returned. If no object matches, then an empty string is returned. If -acceptCallback is given, for each result candidate the candidate’s cell name is appended to $cmd before evaluating it. If it evaluates to false the candidate is skipped.

spos picklist

$db spos picklist ?-limit $limit? (-idx $idx)|$fname $filepos

This command returns a list of OIDs of the object that map to the source file range at the given $filepos (begin <= $filepos < end). The order of the result list is random, except the first element is the one with the smallest range (the same returned by pick). If no object matches, then an empty list is returned.

If -limit is used, the length of the returned list is limited to the given number of elements.

spos foreach

$db spos foreach $oid ?-idx? fname begin end $body
$db spos foreach -all|-grey|... (-idx $idx)|$fname oid begin end $body

The first command loops over all source positions of a given $oid (for some objects like ports or instances there are usually only one source position per object, but in general, objects can define multiple source positions). The second command loop over source positions which are not connected to an object. The $body is executed for each source position at 'OID'; the three variables (specified by their names fname, begin and end) are pre-set before each loop iteration. These loop variables define each source position range.

Here is a trivial "dump" example:

$db spos foreach $oid fname begin end {
    puts "$fname $begin $end"
}
$db spos foreach -all -idx $idx oid begin end {
    puts "[$db oid nulltype $oid] $begin $end"
}

spos foreachfiltered

$db spos foreachfiltered (-idx $idx)|$fname \
        $first $last $oidList begin end $body

This command is an optimized version of $db spos foreach and can be used if only the source positions in a given file range is needed. Also, this command accepts a list of objects $oidList instead of a single object. The $body is executed for each source position found, for each OID of $oidList, which match the given $fname and lie inside the range $first to $last. To match the whole file, you can call $db spos foreachfiltered with first = 0 and last = end.

Here is a trivial "dump" example:

$db spos foreachfiltered "design.sp" 0 end $oidList b e {
    puts "design.sp $b $e"
}

spos foreachrange

$db spos foreachrange \
        ?-acceptCallback $cmd? \
        ?-uniq $cnt? ?-sort? ?-column $b $e? (-idx $idx)|$fname \
        $first $last oid begin end $body

This command is a version of $db spos foreach and can be used if only the source positions in a given file range are needed. The $body is executed for each source position found inside the range $first to $last regardless to which OID it belongs. To match the whole file, you can call $db spos foreachrange with first = 0 and last = end.

Here is a trivial "dump" example:

$db spos foreachrange "design.sp" 0 end o b e {
    puts "design.sp $o $b $e"
}

The -uniq $cnt option suppresses OIDs which have the same type and lie on the same begin and end position as previous OIDs. Instance OIDs are suppressed if there are more than $cnt occurrences. The -column option suppresses OIDs which are not in the given column range.

The -acceptCallback $cmd is called for each OID candidate with appended cell name. If the callback return false the candidate is skipped.

spos foreachfile

$db spos foreachfile ?-idx? fname modtime $body

This command loops over all known source files. The $body is executed for each file and the two loop variables fname and modtime are pre-set before each loop iteration (defining the file name (or index) and the modification time). The file’s modification time is registered at parsing time (when the spos data is created).

Here is a trivial "dump" example:

$db spos foreachfile fname mod {
    puts "$fname $mod"
}

spos exists

$db spos exists $fname

Check if the given file exists in the spos database.

spos mtime

$db spos mtime (-idx $idx)|$fname

This command returns the modification time of the given filename at parsing time (when the spos data is created).

spos maxcolumn

$db spos maxcolumn (-idx $idx)|$fname

This command returns the length of the longest line of the given file.

spos filetype

$db spos filetype (-idx $idx)|$fname

This command returns the file type of the given file.

spos neighbor

$db spos neighbor $oid (-idx $idx)|$fname $pos \
        prevFname prevBegin prevEnd \
        nextFname nextBegin nextEnd

This command fills the given variables with the source positions before and after the source position defined by $fname and $pos. If there are no more source positions in front or after the given $pos, prevFname / nextFname are set to {}.

Miscellaneous Commands

spos delete

$db spos delete $oid

This command deletes all spos entries for the given object. If there are no more spos entries for a file the whole file is removed from the database.

spos clone

$db spos clone $src $dest ?$limit?

This command clones all spos entries from the source ($src) object to the destination ($dest) object. If $limit (a number) is given only the first $limit spos entries are cloned.

spos fnamebase

$db spos fnamebase ?$base?

This command sets/gets the filename base which is used when retrieving relative filenames added with -sposn and -pinsposn.

spos setfname

$db spos setfname (-idx $idx)|$fname ?-short? $newfname

This command changes the stored file referenced by spos to a new file. The new file should be identical to the old file but can be located somewhere else. With the -short option a short name can be set. It has only comment character and can not be used to identify a file in any spos command.

spos getfname

set fn [$db spos getfname (-idx $idx)|$fname] ?-short?

This command returns the stored file name for a file. With the -short option the short name can be retrieved. If none is set an empty string is returned.