Feed on

Thoughts on Verification: svlib - Including the Batteries for SystemVerilog (part 1)

In this edition of “Thoughts on Verification”, Verilab consultant Alex Melikian interviews colleague Jonathan Bromley, lead author of the svlib library. svlib is a free open source utility functions library for SystemVerilog, available on Verilab’s website.

In part 1, Alex and Jonathan begin the discussion by covering why svlib was created, features it offers, as well as some of the internal details of this open source library.

Alex Melikian: Hi Jonathan! It’s great to have you with us. I believe you’re our first ‘repeat’ interviewee on these ‘Thoughts on Verification’ series, so I should really be saying ‘welcome back’.

Jonathan Bromley: Thanks, Alex! I’m sure you could have found someone more exciting from among our amazing colleagues, but it’s a pleasure to be back in the hot seat.

AM: We’re here to discuss svlib, an ongoing project you’ve been working for some time now. Let’s begin by introducing it for the unfamiliar, how would you best describe svlib?

JB: It’s partly a “pet project” that I’ve been thinking about for some years, and partly a response to genuine needs that I’ve encountered - not only in my own verification work with SystemVerilog, but also when observing what our clients ask for, and what I heard from students back when I was delivering training classes before joining Verilab. It’s a package of general-purpose library functions covering string manipulation, regular-expression processing, file access and operating-system interface stuff such as wall-clock time and directory exploration, and a bunch of other utility functions. Almost all are things that - frustratingly - aren’t available in standard out-of-the-box SystemVerilog, but exist in just about any general-purpose language. With svlib added to your toolkit, SystemVerilog starts to look a lot more like a competent all-round programming language.

Most of the non-trivial functionality in svlib is implemented using SystemVerilog’s fantastic C-language interfaces, the DPI and VPI. For many years, folk who are expert in both SystemVerilog and C/C++ have used those interfaces to implement their own additional functionality. The contribution of svlib, I hope, is to make a wide range of useful new features freely accessible to anyone who’s familiar with SystemVerilog. No C or DPI expertise is needed to use it.

AM: It’s interesting you’ve discovered so many things that would have been nice if it were already included in SystemVerilog, even though its LRM is over 1300 pages long. So let’s pretend I’m a manager with an important meeting to attend in 60 seconds. How can you convince me that svLib can be a good addition to the tools that already exist?

JB: 60 seconds, that’s tough! Let’s try… Chatting with your engineers, I see that they are writing quite a few external scripts for functions that they would prefer to be part of the core verification environment. Stuff like text processing, messing with environment variables, creating data files for later processing. There’s a free library, svlib, that can do those things from within SystemVerilog. It fits nicely into any verification methodology including UVM, it doesn’t need your team to learn a new language, and it would let them put that processing back into the verification environment in a consistent way. The licence is very permissive, so there’s no legal hassle. It has a decent user guide, and did I mention it’s free?

AM: (Laughs) … well done Jonathan! I think our readers will appreciate that response if they’re put in a similar spot. Let’s talk about these features currently available with svlib. You’ve mentioned a few, and there’s more to get to later, but let’s start with text processing and creating data files. When most people think of these operations, they will think of the file I/O operations already available in SystemVerilog, or even Verilog. However, am I right to imagine svlib offers more than the just the standard file I/O?

JB: Of course you’re right that SystemVerilog already has a good range of file I/O features available through the $display, $scanf and related families of system functions. However, something I’ve always felt was missing in SystemVerilog, was a way to explore the file system or query the status of individual files. svlib does just that and allows you to find out about file sizes, creation and modification dates, permissions and so on. It does this by calling out to standard system library functions via the DPI [Editor’s note: Direct Programming Interface, see SV 1800-2012 LRM clause 35]. You can also use svlib find the contents of a directory, using the familiar “glob” wildcard syntax such as “*.sv”. The results come back as a simple SystemVerilog queue of strings, one per file. Those features, which I loosely think of as operating-system interface, are rounded-out with the ability to query environment variables, wall-clock time, and the current working directory.

The result of all this is that your SV simulations can now be much more flexible and robust in the way they use files. If a file-open operation fails in regular SV, you really have only two options - continue without using the file, or stop and display an error diagnostic. With the ability to explore the file system using svlib functions, you now have the choice of using an alternative directory, looking at environment variables to decide where to find files, and many similar fallbacks that programmers writing in an ordinary software language would do as a matter of course. Having access to wall-clock time and date is really useful, too, especially for adding timestamp information to log files and for doing simple performance measurements.

There are some other file manipulation functions, such as file copy, rename and delete, that I considered adding to svlib. But then I realised that you can easily do those things in SystemVerilog already. All you need to do is to use the built-in “$system” function to execute an ordinary Linux command such as “cp oldfile newfile”. So I was quite careful to limit svlib’s contribution to things that can’t be done in a direct, simple way from regular SystemVerilog code.
One final thing that might be worth mentioning: something I used to find myself doing over and over again in SystemVerilog is reading a text file, processing one line at a time. svlib provides a little macro to do that - it’s called “foreach_line” and it works almost exactly like a foreach-loop. You can provide any loop body, enclosed in begin…end if you wish, and that will be executed once for each line in the file, with the line stored in a variable of your choice. This isn’t rocket science - it’s only a 5-line macro! - but it’s a real labor-saver.

AM: That does sound pretty neat. I agree that these features do not sound like operations that are overly complex in nature, but they seem to be things that would be very handy to have when needed, and conversely, frustratingly counterproductive if unavailable. I can see the point in your initial description where svlib is filling these gaps in the standard SystemVerilog language. After all, with designs getting unrelentingly complex, we as verification engineers don’t want to spend our time in the weeds over file I/O details, but rather simulate and find as many bugs as we can in the DUT.

There is one type of file operation in a category on its own: configuration file handling. I feel we should bring this up separately since svlib has specialized functions dealing specifically with this. So what is currently available in svlib someone can use for configuration files?

JB: Just about any nontrivial testbench needs to read setup or test-configuration information from some kind of text file. Verilog already has a standard file reader mechanism in readmemb/readmemh, but that’s only designed for preloading a memory and it has no support for any kind of named data items. My goal for svlib was to be able, with just one or two function calls, to dump the contents of any SV object into a data file, with items in the file being tagged with the same variable names that the user created in their object. And then, of course, we should be able to read such a file back into a suitable object, again with just one function call. Finally, the file format should be widely supported, and expressive enough to represent any SystemVerilog object structure.

Armed with that functionality you have a single, uniform way of transferring configuration, setup and other data between a testbench and any external script or program. The most obvious and important application, I think, is grabbing setup data that’s been created externally and using it to configure your testbench - for example, loading a UVM agent-configuration object directly from an external file.

For this to be useful, it’s essential that the transfer is fully automatic, for any object that a user may throw at svlib. Making that work well is quite tricky - but we came up with a solution (you can find the details in our DVCon paper), and svlib already supports it for the popular “.ini” file format. That’s useful, and it’s a nice proof -of-concept, but it’s not really powerful enough for industrial-strength problems. I’m working on making the same functionality available with the much more expressive YAML file format. If it weren’t for the dratted day job getting in the way, I’d have had that finished months ago! This area of svlib’s functionality was by far the most challenging to design and to implement, and it’s taken a while to think it all through.

AM: Hold that thought for a moment. First, I would like to mention to our readers that documentation is currently available along with the svlib source code on the dedicated web page. Our readers can keep an eye on that page for updates and feature additions, such as the YAML file format, as they become available. Or, better yet, follow us on twitter to receive notifications in real time.

Back to your last comments, it sounds like you’ve designed the class definitions dealing with configuration files to be flexible for different file formats. If someone would have some legacy infrastructure to deal with like custom made configuration files and would like to interface it with svlib, would they able to do so?

JB: Good observation, the answer is ‘Yes’. svlib uses an intermediate tree-structured representation of the data, which provides complete separation of the two concerns - transferring data to and from a user’s SV object, and copying the data to and from an external file. The tree representation is a good match for any reasonable structured file format such as YAML or XML, and it could even map to a database. So you’re right to surmise that users could, in principle, write their own data file reader/writer without too much difficulty. The object-to-tree side of things is done already, and anyone implementing a new file format would not need to worry about that at all. If you already have reader/writer software for some file format, then I guess it would be at most a day or two’s task to adapt it to work with svlib.

Documenting that kind of flexibility is quite a challenge, though, and it’s been on the back burner while we put our efforts into creating accessible documentation for the more common user-facing features. Meanwhile, if someone comes along with a request to do their own file format, I’m sure we can figure out a way to help make that possible.

AM: Sounds reasonable. You do, after all, have a day job to attend before you turn into some sort of Systemverilog ‘Batman’! Or perhaps you’re more of a Systemverilog ‘Alfred Pennyworth‘?

JB: Oh dear, my cultural ignorance is showing - I had to Google for Alfred Pennyworth. I think I’m rather flattered, but I’m not sure!

AM: Oh, I assure you it’s all in good faith. Jokes asides let’s move on to another feature I would like to talk about in svlib: operations with regular expressions. Now, I have to confess, when I think about regular expressions, I can only think of scripts and command line operations. Before you describe the regular expression functionality available in svlib, could you give me an example where such functionality would be handy in a test bench?

JB: I agree that, at first blush, regular expressions aren’t a feature you would instinctively associate with verification. However, it’s interesting that the UVM library now includes some regex functionality - it’s used, among other things, for matching names when searching the config database. So I feel I’m in good company.

I’m not sure about other people’s experience, but I have often found that I need to do various little bits of string processing in a SystemVerilog testbench or verification component. A few examples: tweaking text output from the simulation to get the log file the way I want it; checking the validity of command-line “plusarg” options; pulling information from files; pattern-matching of error messages when writing UVM report catchers. On many occasions I’ve found that the regex toolkit changes some desirable string processing task from “sadly we don’t have time to do that” to “that’s easy, just a couple of function calls”.

Did you know that standard SV has absolutely no facilities at all for searching for text within a string or file? Not even a simple “can you find this small string within that larger one”. I can’t think of any other language that offers string manipulation but is so hobbled for string searching. You could argue that regexs are a very big hammer to crack that rather small nut - but why not have a fully general mechanism, if it’s easily available? The full range of regex functionality is available in svlib, including sub-matches and search-and-replace substitution.

I noticed very recently that one of the major simulator vendors has now added some non-standard extensions to SystemVerilog, supporting regular expressions as additional built-in string methods. Obviously that’s nifty for their customers, but it’s not very useful for anyone who, like the Verilab team, wants to write code that will work on any major vendor’s tools. I firmly believe that the bolt-on library approach of svlib makes more sense for this kind of functionality, and it does work across all major tools.

AM: Ah, I get it! We, as verification engineers, are not just building a testbench to simulate a design, but a testbench we can debug a design with. Which means the testbench should be able to produce enough clear information when needed, like log files or additional data files, enabling the team to isolate a problem. This is where regular expressions can play a role.

As you alluded to earlier, the extra bells and whistles provided by svlib through “just a couple of function calls” can really help the verification team produce something to accelerate the debugging process.

JB: As verification engineers we have only one goal: to find the bugs before tapeout, so that the tapeout is as close to bug-free as we can make it. There’s no obvious one-to-one connection between that goal and purely software ideas like regular expressions. But as we put our aims into practice, it certainly is true that we find verification to have a big software component. To be good verification engineers we must also be competent programmers, and anything that makes our programming lives easier can be a step up to doing verification better. So I don’t feel a burning need to justify every individual feature of svlib in terms of a specific hands-on verification problem. svlib is a toolkit, and I hope it will be judged on its general usefulness - not because it hits any one particular application task.

AM: That’s some interesting insight. Sometimes, it helps to understand the philosophy behind something, be it a programming language, library or other tools, in order to better grasp how it can be used.

End of Part 1

Leave a Reply

Enter the letters you see above.

Work For Verilab