Xilinx documentation typos

While I like Xilinx and think their docs, if you read enough of them you will find three things

1. Some things that aren't documented enough
2. Some things that aren't documented at all
3. Some things that aren't documented correctly

---Matthew Hicks

1. Some things are documented somewhere, but good luck finding it.

Yes, I went through a discussion in this group a while back about information that seemed to be missing from the Spartan 3 data sheet, but in fact was just well hidden. It was scattered over a large portion of the document rather than being in one place. After a lot of discussion, one of the Xilinx regulars here had the data sheet amended to help with the problem. Of course it really needed a thorough review and much more extensive editing, but that was a start.

I also got Atmel to amend the AT91SAM7S data sheet to include enough info on the crystal that you can almost spec one to use.

Documentation is often the poor stepchild of a development process. I know where I work there are tons of instructions and procedures and processes on how to prepare documentation. Then the documents that result are hard to understand, incomplete and sometimes even wrong. It can take forever for them to be updated because there is no incentive to return to them once they are completed.

Personally I take pride in the documents I prepare. I never want anyone to read one of my documents and think it was written by a moron, even if it was! ;^)

Same here. Through the XC3000 and XC4000 generations, I put together every databook, from deciding the format and pagination to writing much of the text, to negotiating the detailed descriptions and even the parameter values. It was pretty much a one-man show. But the parts were simple... Then Xilinx got bigger and various people had to share the "fun".

Documenting programmable logic may be more difficult than documenting memories, microprocessors or ASSP dedicated circuits. FPGAs are used in a myriad of ways by hundred thousands of designers with widely varying backgrounds and skills.

The person(s) in charge of documentation must be technically savvy in a wide area, be able to write clear and reasonably tight English sentences, have the eyes of an eagle, and the patience of Job. They must be self-confident and persistent without becoming obnoxious, and it helps when they have a respected and senior position in the company, so that they can circumnavigate committees and get things implemented or changed. That's a tough job desciption. No wonder we do not always live up to the highest expectations. But we are still trying... Peter Alfke, Xilinx, fom home

Peter Alfke schrieb:

Peter,

yes it looks the Xilinx documentation situation is way more complex now.

after woopla with Virtex-4 (symon in printed documentation, sysmon in silicon - but disabled by software tools) Xilinx seems to be more careful not having data in datasheet.

Virtex-5 (at least LXT) is claimed to be available NOW - in the matter of fact it is I have both parts and Xilinx SEG manufactured development board, but the datasheets are not yet available. Or ok there are datasheets available with partial information.

I assume the datasheets will be fixed with next ISE service pack but at Xilinx website there is not schedule for the next ISE SP!

current Virtex-5 datasheets dont have any information about

1) sysmon 2) R_FUSE and VFS pins 3) possible several other things (I havent looked if the CRC32, CRC64 are documented)

ok, this is new product development related.

but when I opened webcase because of errors in Coolrunner datasheet then the Xilinx response was, what you think? Fixing the datasheet? No the information was just removed, not fixed. It was regarding MC term numbers, it is not important to most of users, ok it is maybe only useful for those who write a PLD fitter. Still the partially available and wrong information was not fixed but removed (after my webcase).

Antti

Antti, As I write this, V5LXT (and SystemMonitor) has not yet been officially announced or released. But, hold your breath, it will be "soon". As I mentioned once before, a Product Announcement is a rutual dance, involving not only Xilinx, but also the press. And they are obsessed about the "virginity" of the information. So we have to keep mum. But soon we can discuss this openly. I am glad you got the ML501 board faster than anybody thought. But it has an 'LX, not LXT device on it. We will look at the other points in your posting. Peter

"Peter Alfke" schrieb im Newsbeitrag news: snipped-for-privacy@e3g2000cwe.googlegroups.com...

smiling here - I was excited about sysmon in Virtex-4 so it was obviously the first thing I wanted to check out on Virtex-5, I was almost to try out the V-5 sysmon based on the information from Virtex-4 datasheet and trial and error, but decided to wait a little (but I am really bad at waiting!)

from what I understand it is available in LX50 (except the lack of documentation).

regarding the CRC32/CRC64 I should have double checked they are only in T parts, so I assume they will all be documented with the official release of LXT devices.

I am just wondering -

1 the LX parts are shipping, but full datasheets are not available 2 LXT parts seem to orderable, but are not announced 3 LXT parts have passed PCISIG PCIe compliance

there seems to be lot of things going on, but very little exposure.

hm.. I hope thist time there will be a PCIe capable board made by Xilinx/SEG the competitor Lattice has already 4 different boards (2 different FPGA families) with PCIe capability. Sure there are some 3rd party Xilinx/PCIe boads available, but if Xilinx/SEG made board is available I will almost sure prefer the Xilinx direct board.

Antti has to go make panncakes now.

"fun"....>>>

I met you in 1999, Peter.

I won't say where, lest I reveal my identity.

You bragged about how Xilinx "..doesn't have technical writers. Our engineers do our writing...>>>

Quite frankly, sir, it shows.

"fun"....>>>I met you in 1999, Peter.

And, IME, be willing to work for 1/2 to 1/3 of an engineer's salary. I am amazed at how little tech writers get paid.

salary.

Hello Peter,

I'm taking advantage of you responding:

What's the proper procedure to feed back documentation typos to Xilinx ?

Back to the original post, i'm now able to be more precise on one of the above errors:

• ug191 v1.2, table 6-7 page 103, the block type 001 is block RAM content and BRAM routing is actually included in standard, type-000 frames. type 010 should be scrapped as bram type, as now seems obvious from re-reading the table.

I'm also a bit puzzled about documentation inconsistencies between device generations, for instance from virtex4 to virtex5. The virtex4's configuration frames contain the exact same 12 bit Hamming ECC code, at the very same position as described in the ... virtex5 documentation. If Xilinx chose not to make the information public for the v4, how come it's now cleartext in the v5 documentation (not that i'm complaining...) ? Why not at least a pointer in the v4 doc to direct people to the v5 doc ?

JB

Here is the response from the responsible group within Xilinx:

"For documentation such as data sheets, user guides, app notes, and similar documentation please use the "Helpful?" link under each doc: This will pop-up a simple form that can be filled out with feedback for the specific document which will then be funneled into the appropriate group. The customer does have to acknowledge that Xilinx will not respond directly to the feedback.

If the feedback is on software documentation that is produced by DSD for ISE/EDK, you can send the feedback to snipped-for-privacy@xilinx.com.

I h> Hello Peter,

This is the official answer from our support organization: "The proper procedure for feeding back documentation typos to Xilinx (as well as for requesting technical support) is to use our great WebCase tool, which will help Xilinx to efficiently capture all relevant information about the issue up front. It can be accessed here:

.

Other helpful technical support resources can also be found here:

Describing WebCase as "great" for documentation errors is (cough, hack) a bit of a stretch; have you ever filed one ?

( If not, the next time you find and report, say, a particularly sneaky FIFO flag bug, wait a few months for your internal paperwork mill to grind- then pseudonymously file a WebCase describing exactly that same problem, and see what happens... )

Filing documentation error reports through a WebCase is particularly time consuming and pointless; my experience has been that Xilinx essentially refuses to fix the documentation problems no matter how painstakingly detailed the report.

The WebCase will be closed as rapidly as possible by Xilinx, possibly without the first responder even understanding the documentation problem.

If you are persistent, you can get some CR's filed, at which point the WebCase will then be closed; none of that persistence will result in any good, as the CR's then vanish into the mists.

Post-WebCase, nothing happens: - datasheet errors and omissions persist - Answer Records remain incorrect - software bugs remain ( or perhaps worse, reappear in a version or two )

At best, years later there may appear a cryptic Answer Record or an indecipherable footnote that bears almost no resemblance to the original problem report.

AFAIK, there's no way to track a CR's status without opening a new WebCase and asking again; if you're lucky, the link on your WebCase history page may actually display the old WebCase text without locking up your browser.

And to top it all off, if you then post a summary of said problems here on comp.arch.fpga, you run the risk of being flamed by Xilinx's own Troll of Implausible Deniability.

Brian

Brian, in spite of (or because of) your nasty tone, I will on Monday submit this to the responsible group in Xilinx support. Just a few comments: Not everything is just a documentation fault.

The unfortunate and very subtle Virtex-4 FIFO flag problem haunted us for many weeks, until we had found the cause and a barely acceptable work-around. (I was > Peter Alfke wrote:

errors

Please explain exactly what it was you found "nasty" about my post?

I described my own experiences with documentation WebCases, and suggested that if you've never filed one, you should give it a try sometime, for a problem you've been involved with, to see for yourself what users find so frustrating.

I mentioned the flag bug not as an example of something that needed documenting, but merely as an example of something, with which you were familiar, to try opening a Webcase.

I haven't looked for this information in the V4 datasheets, but Answer Record 22462 has a well written description of the flag problem.

Brian

was you found "nasty"