Origen::Specs docs don't match API behavior

[info-rchitect]

Hi,

I am just getting back to using the Origen::Spec module and see some differences between the docs and the actual API behavior. The docs say:

_If any of the options are nil it will not filter by that option when interrogating the spec database. The API is:

specs(:myspecname, options) In the example above a symbol is passed for the spec name but all four filter options can be a String, Number or a Regexp. If an object defined three specs named :soc_vdd, :io_vdd, :pll_vdd the following call would occur.

specs(/vdd/,verbose: true)_ If the ‘verbose’ argument is not included, only an array of spec objects is returned. If only a single spec is found a Spec object is returned instead of an array of a single spec.

And here is the actual behavior:

origen(main):001:0> $dut.jtag.specs
=> [:frequency, :voh, :vol, :vih, :vil, :dcdrx, :dcdtx, :cin]
origen(main):002:0> $dut.jtag.specs(/^v\Sh/)
=> [:voh, :vih]
origen(main):003:0> $dut.jtag.specs(/^v\Sh/, verbose: true)
=> [:voh, :vih]

Here is some other odd behavior when the user specifies a spec ID that is defined in multiple modes and sub-types:

origen(main):001:0> $dut.miscio.specs
=> [:frequency, :vih_ac, :vih_ac, :vih_ac, :vih_ac, :vih_ac, :vil_ac, :vil_ac, :vil_ac, :vil_ac, :vil_ac, :dcdrx, :cin, :cin, :cin, :iin, :iin]
origen(main):002:0> $dut.miscio.specs(:vih_ac)
=> [:vih_ac, :vih_ac, :vih_ac, :vih_ac, :vih_ac]

I also don't see any documentation on how to iterate over specs (i.e. return the objects themselves vs the IDs). Does anyone know when this disconnect occurred? I think all of our main object classes should behave nearly identically. I believe the new PowerDomains and Clocks modules behave as desired by the Origen core team. Any info is greatly appreciated as I intend to use Origen::Specs a lot in the future :)

EDIT:

After reviewing the Origen::Specs module, I am not sure it can exist as-is. When I first coded this module, I was the only person using it and I made poor decisions regarding how much application specific modeling I included. Now that there are other users, I propose the following:

• We make plans to deprecate this version of Origen::Specs in version 1.0. Between now and then, I will code a new version that mimics other Origen models. This will give other users time to migrate all of the application specific modeling to their apps.

Help needed: For anyone using Origen::Specs, please start an RFC that details the requirements. Please be sure to examine what is application specific and what should be part of the Origen core model. This RFC should detail Notes, Features, etc.

Thoughts?

[ginty]

Your proposal seems OK to me

[coreyeng]

Hi @info-rchitect,

I've been somewhat using specs, though I've extended the API myself in one of my apps. I intended to check this back in but its been a... very slow work in progress. Anyway, I too have found the current specs API to be a bit lacking and would be interested in collaborating with you for a new API.

Anyway, one of the requirements I have is to embed specs within specs, which I think is what @ginty is discussing in #151. What I have now is this (sorry this being a screenshot to an internal web page):

(ignore that is says 'parse', I recently changed it to 'tokenize' instead to better match what it does. these are all still preliminary docs)

So, that's how I've been using specs. This is all for ATE generation though, but I'd like to be able to generate a reference webpage too. I'd like to use the same API for spec creation then let the datasheet API and OrigenTesters figure out how to actually use the spec for their purposes.

Obviously I'm not evaluating anything, so its not exactly what was discussed in #151 but I think its along the same lines. I could also change it to use single quotes so that we can put full ruby blocks in the specs. I think we'd just need to change lint to ignore the "/' in specs (not exactly sure how that would be done though without just getting rid of the "/' checker entirely).

Let me know if this is along the lines of what your were thinking.

[info-rchitect]

@coreyeng nice writeup, it makes it very clear that the following statements are true:

1. Origen::Specs is valued and needs an update
2. We need it modified now and another round of testing by the concerned parties

I will enhance the existing PR t o implement the single quotes.

[coreyeng]

@info-rchitect Thanks! But also, I've got it working now with the '@' symbol since I don't need to evaluate. So don't feel the need to add this if its not needed for what you're doing. I can always add it later too.