IP-XACT: IEEE 1685-2014 and how to deal with elements, that do not exist?

[Ralf Hildebrandt]

IEEE 1685-2014 provides the <isPresent> element. Chap. C.10.2 says "When nonpresent, the enclosing element and all of its descendants shall be treated as if they do not exist in the file." But what does "not exist" mean?

Let me explain the problem by an example: In a hardware peripheral there is a status or control bit, but this bit is only available if an optional feature is enabled. The feature can be selected / deselected before the hardware peripheral is implemented. This means, that the related flip-flop is included in the hardware or not. But if some software reads from a register (= from an address) that contains that field (= contains this status / control bit) what behavior can the sofware expect if it does "not exist"? The most straightforward expectation is "read-only, read as 0". But it is imaginable, that it could be also "read-only, read as 1".

I was unable to find any definition inside IEEE 1685-2014, that defines what can be expected it something does "not exist". Does this mean, that it is not defined by IEEE 1685-2014 and therefore is implementation-specific? If implementation-specific how we can deal with the fact, that there may be (software) tools, that read an IP-XACT XML and may do the interpretation of something, that does "not exist" in a different way?

 

And now comes the real tricky part: What if a field is <virtual> and located inside an <address block> where the <usage> is <memory>? What if such a <virtual> <field> does "not exist"? Does this mean "read-only, read value unknown" or "readable+writable, read value unknown" or something similar? For details about a <virtual> <field>, see:

 

Next: typical address maps will contain "holes" (unused addresses) and register words may also contain "holes" (unused bits). Those "holes" also do "not exist" in an IP-XACT description. What do tools expect how those "holes" behave if a read access is done to such an "hole"? (In other words: The question is not limited to <isPresent>.)

 

Or is there an easy way of how to define the behavior using IP-XACT? It did experiment with defining "holes" in registers as "reserved". But the problem is, that If I define a bit, I have to give it an unique name (unique at least for <fields> inside the same <register>). So it becomes rather ugly to define a bit with e.g. name "reserved_1" and "reserved_7" (if both bit positions 1 and 7 are "holes" and do "not exist"). In addition to the ugly names these definitions will be propagated through all tools (e.g. for software header file generation). This may cause trouble for header files, but becomes a nightmare if some (human-readable) documentation is automatically created by parsing the IP-XACT description.

 

Many thanks in advance
Ralf

[kock]

Hello Ralf,

The term "non exists" means that the XML file shall be read/processed in such a way that the enclosing element is not present in the XML file. Please note that the value of isPresent elements is an expression in terms of IP-XACT parameters. So it is possible that you can only resolve the expression when all IP-XACT files have been processed since parameter values may "propagate" from one file to another file.

If your virtual field does not exist, then it means that that part of your memory map contains a "hole" as you call it. You may try to describe another field for that "hole" that has another isPresent expression such that the "hole" is always filled depending on your isPresent evaluated values. I would advice to avoid that complexity. Rather it is simpler to write a "generator" (script or program) that generates the IP-XACT file and uses the configuration parameters of your configurable IP. In that way, you always generate a configured IP-XACT component that matches with the configured IP that you want to integrate.

In general, "holes" in address blocks (including registers) means that something is not documented. An address block represents a contiguous piece of memory. IP-XACT does not describe what these holes mean.  IP-XACT also does not describe what "reserved" means. If you perform a read access on a "hole", then the behaviour is completely tool and protocol specific (not defined by IP-XACT). For instance, with APB2 you may read zeros (or ones, or undefined), while with APB3 you may get a slave response error.

The IP-XACT schema also contains display elements. A documentation generator may use the displayName element value rather than a name element value. In this way, reserved_1, reserved_2, and so on are the unique names of your fields. The displayName element values can all be reserved; these do not have to be unique.

I hope this helps,
Erwin

 

[blewis]

BTW... it appears this isPresent construct has been removed from the 2022 spec.

[kock]

Yes, that element has been removed from the standard to reduce its complexity. We decided to move that element into an Accellera vendor extension. That vendor extensions schema will be hosted on the Accellera website as well. For instance,

<ipxact:port>
  <ipxact:name>my_port</ipxact:name>
  …
  <ipxact:isPresent>
    …some Boolean expression…
  </ipxact:isPresent>
<ipxact:port>

will be converted to

<ipxact:port>
  <ipxact:name>my_port</ipxact:name>
  …
  <ipxact:vendorExtensions>
    <accellera:port>
      <accellera-cond:isPresent>
       …some Boolean expression…
      </accellera-cond:isPresent>
    </accellera:port>
  <ipxact:vendorExtensions>
<ipxact:port>

[Jason H]

Quote

In a hardware peripheral there is a status or control bit, but this bit is only available if an optional feature is enabled. The feature can be selected / deselected before the hardware peripheral is implemented. This means, that the related flip-flop is included in the hardware or not. But if some software reads from a register (= from an address) that contains that field (= contains this status / control bit) what behavior can the sofware expect if it does "not exist"? The most straightforward expectation is "read-only, read as 0". But it is imaginable, that it could be also "read-only, read as 1".

The concept of isPresent is incredibly useful, in my opinion. However, it is difficult to implement in practice because you have different use cases and you need to define exactly what being non-present means for your team. As @kock mentioned, the standard does not detail the specifics of these things (I don't think it would be feasible).

It is reasonable to treat isPresent=0 on a field the same as reserved=1 from a software point of view (though, as also mentioned above, reserved is up to interpretation). That wouldn't work in concert with the idea of a separate field with an inverse isPresent expression at the same address. I have found it useful to align with some of the rules in SystemRDL 2.0, which also has an ispresent property, but your mileage may vary.

TL;DR
I do think a field which is "not present" returning a non-zero value on read would be unexpected by most.