( ESNUG 447 Item 10 ) ------------------------------------------- [09/26/05]
Subject: ( ESNUG 446 #8 ) Denali's Proactive Response to its PCI Doc Issue
> At first glance, it looked like Denali's PureSpec PCI Express was a
> pretty solid and well-documented verification environment. That's until
> I started trying to do meaningful activities with it. This environment
> has very inadequate documentation. ... Denali would benefit from some
> extensive rewrites of this 18-month old documentation. ... This is also
> not intended to slight the quality of the Denali PCI product itself; once
> I do figure out how to get the tool going, it seems to be pretty solid
> and versatile.
>
> - [ Teller of Penn & Teller ]
From: Sanjay Srivastava <sanjay=user domain=denalisoft spot calm>
Hello [Teller],
Thanks for pointing out the deficiency in our documentation, and also for
your kind words on our PureSpec PCI product.
You are a very important customer for us. I went back and asked my team
to look at the issues you raised, and I was a little embarrassed to find
out that we have indeed not met expectations on the quality of the
documentation. I have since issued a challenge to the team to address
your concerns and come up with a new solution over the next 60 days
which can make us proud of not just the product, but the documentation
as well.
To be honest, I personally did not realize the magnitude of the challenge
we were embarking upon when we committed to developing our PCI Express
verification IP over 3 years ago. After dozens of engineer-years invested
and continuous feedback from almost 100 of our customers like yourself, we
are still finding places to improve.
Early on, we had made the completeness of our models, in terms of
obsessively covering all the error checks, as our top goal followed by
making sure that we do a good job supporting state-of-art verification
methodologies. And of course, we needed to deploy a team of world-class
PCI Express experts to help with support.
Documentation had unfortunately not made it to the top of the list of
areas we were striving to excel, and clearly this was a mistake. I am
sure that you will see plenty of innovation from us soon in this area.
We are creating lots of ways to auto-generate documentation from the
source code, possibly create a web community of our customers to solicit
more active feedback, and of course, there will be a lot of hard work
and sweat behind resolving this issue.
Once again, sorry for all that we put you through. You have my commitment
that the company will get behind resolving this issue. In fact, just in a
meeting today our VP Engineering promised a whole new look for our
documentation by Dec 31st, and not just for PCI Express, but for all of
our verification IP.
- Sanjay Srivastava, CEO
Denali Software Palo Alto, CA
---- ---- ---- ---- ---- ---- ----
From: Sanjiv Kumar <skumar=user domain=denalisoft spot calm>
Hi, John,
I would like to take this opportunity to follow up on [Teller's] posting
about PureSpec's documentation.
Denali's product team recognizes the need for improvement in our
documentation and is actively working on the issues raised by [Teller],
and others via our support channel. We are encouraged that the actual
product is robust, and I'm confident that we can address the
deficiencies in the product documentation.
With respect to specific comments raised by [Teller] --
> Denali supplied a user's manual and a reference manual. There are
> items in their reference manual (like how to install the product) that
> ought to be in the user's manual. There are items in the user's
> manual that ought to be in the reference manual.
We have a two-phased approach to improving PureSpec documentation. In
our first phase, the team has focused on completeness and accuracy of
the material while in second phase we will focus on presentation, flow
of contents, readability, cleanup of the document, etc.
We have already had an extensive review of over 600 pages of our
documentation for completeness and accuracy, and have made many
additions to fill holes with more details and examples. Our ongoing
efforts to improve on the contents and keep the documentation in sync
with the product are paired with a plan to develop some technologies to
help with this task.
For our second phase, we have identified some high-level requirements.
The documentation team is committed to focus on following items --
1. Merge PureSpec PCIe User manual and Reference manuals
2. Remove redundant content
3. Improve organization of material and readability:
a. Add document index, list of figures, jump list,
cross-references etc.
b. Improve content flow and grammar
c. Improve clarity and consistency
d. Add graphics, tables and screenshots (where required)
e. Reconsider presentation of material (text vs figures vs
tables etc.)
4. Adding more examples/details for different usage scenarios
5. Re-organization of some part of documentation
6. Make document easier to maintain.
> There are no field-by-field descriptions of what's in the Denali PCI
> Express packet type that's used to generate the transactions. There's
> also no indication of how wide each field is. I'm continually
> consulting the source files to figure this out. Our previous PCI-X
> and PCI test environments licensed from another vendor *did* document
> every field and I rarely had to go digging through uncommented source
> RTL to get an answer.
[Teller] correctly observes that field-by-field packet description was
missing in documentation. As a consequence, users did need to refer to
Denali source files in order to figure out field width, etc.
This is good input, and we have since addressed this in our current
documentation release. We have also added more sections and tables,
which clearly describes each packet field, width etc. for all PCI
Express TLP, DLLP and Ordered Set packet types.
> Information about how the transaction log file is formatted is
> supplied in an appendix tucked at the end (page 326) of the reference
> manual. I had no inkling that memory space transactions would print
> the payload bytes in big-endian order while configuration space
> transactions would print them in little-endian order. The example on
> pages 73 & 74 of the Denali user's manual shows an excerpt from the
> transaction log, but doesn't even have so much as a footnote telling
> you that the byte ordering can be different or recommending that I
> consult the appendix. I spent an hour investigating our DUT for errors
> before I suspected that there was no problem at all.
As [Teller] mentions, we have an appendix [TLP Payload Byte Ordering] in
the PureSpec reference manual that describes byte ordering in detail.
Although it is listed in the table of contents, it may not always be
obvious where to find this information, so to address this particular
issue, we have since added a prominent cross link to this appendix under
payload packet field section.
Moving forward, as we described above, our team will focus on improving
the ease of search/find to locate all relevant information (using cross
link, jump list etc.) on the various topics that are available in our
documentation.
(BTW, the Denali configuration space is a Dword aligned (4 bytes, or
32-bits) and it follows little-endian formation, in sync with the PCI
Express Configuration register layout. The memory space, however,
follows big-endian formation, which is also in sync with the PCI Express
payload layout. All the transactions get printed as [Teller] describes
above.)
> No explanation was given on how to get the data collected from a read
> transaction. I was fortunate enough to figure it out on my own, but
> not everyone might figure it out.
Many users consider the PureSpec callback mechanism as one of the most
powerful and flexible verification features available. As such, the
PureSpec User manual has devoted a entire chapter on our model callback
mechanism, and describes how users can register callbacks to intercept
packet activity to inspect or modify packet fields as per verification
requirements. The possible scenarios for packet and traffic
manipulation in PureSpec are infinite.
A specific example of the scenario was not given in the documentation;
however, we have since added it in the callback chapter. Our
documentation team will continue to add more examples to cover common
scenarios.
> The examples explaining how to interface the Denali tool to Specman
> has some glaring holes. I spent a few hours this afternoon realizing
> that the reason why I couldn't get Specman to come up with the PLI in
> the new environment was because there was some C code that had to be
> compiled and linked into the design. No mention of this anywhere in
> the Denali documentation -- just three commands Denali said to enter
> that results in an error message from the simulator because it's
> missing the aforementioned code. Why is there no PCI Express example
> in the distribution for Specman?
Although Denali provides a few scripts in our installation directory to
build the necessary objects to use the Specman (or VERA, C, SystemC, or
other) interface with various simulators and different platforms, as
[Teller] mentions, our documentation omitted some requisite Specman
integration compilation commands. We have already addressed the
documentation issue, and we also plan to address the Specman-PureSpec
integration with an example in our next release.
We would like to thank [Teller] and others for their valuable feedback.
We look forward to this opportunity to improve our users' experience and
I am confident that you will see a marked improvement in our
documentation moving forward, not just with our PCI Express offering,
but also with Serial ATA, Ethernet, USB, AXI, CE-ATA, etc.
- Sanjiv Kumar, Manager of CAE
Denali Software Palo Alto, CA
Index
Next->Item
|
|
