Spartan 3 documentation confusing...

Rick,

Why not just email all of this to Steve Knapp directly? Or me or Peter for Virtex parts?

Seems that if you'd like to help us by pointing out anything confusing or inconsistent, you could get it to the right party in one step.

I agree with you that answers should be scrubbed for any update to a document. It is the little things that drive us all crazy.

Austin

rickman wrote:

I *didn't* address the message to anyone at Xilinx. This was an open message to everyone who uses Xilinx parts and might have something to comment about it. If you review the other thread on the documentation shortcomings of the Spartan 3 parts, you will see that at least one poster has encountered such signficantly difficult to resolve issues that they consider the solution to be proprietary information.

You are a big proponent of how good a job Xilinx does on support. Instead of asking why I posted the message, have you considered asking why a significant issue such as 1 kohm pullup resistors on the configuration pins remains largely undocumented? It was only after I found that confusing sentence shown below that I realized that these resistors are also on the JTAG pins. I have been asked repeatedly why I did not use a pull down resistor on JTAG my board like the other designs here use. My answer was that this is what I am used to using. I nearly changed the design since I had no strong conviction either way. Now I realize that if I had used a pull down of typical 1 to 4.7 kohms, the circuit would not have worked at all being biased in an undefined region.

Come on Austin. Don't shoot the messenger! Listen to the message and work on your internal processes. If it was important enough to create an answer record and was not in the data sheet, someone should have made sure that it found its way into the data sheet in a clear and accessible manner.

BTW, I still don't know if the configuration pullup resistors are disabled by the HSWAP_EN signal. Anyone out there know the answer? I really don't know if Xilinx does. I would love to see a clear and comprehensive table covering all the pins.

Aust> Rick,

Rick!

Back off -- I am on your side.

I am just asking that you send comments to the appropriate person in Xilinx (too).

Go ahead and post (it is your time, and your effort). I don't have a problem with that. But, if you post something that can be fixed, at least give us the oppostunity to fix it. If we screw up, then OK, scream and rant, and do whatever makes you feel better.

Its a big company, with many products, and millions (literally) words of documentation.

I didn't say we were perfect. In fact I said we were imperfect, and looking for ways to get better.

I have spent about two hours today trying to identify where in the process APD and GPD could do better. I am still trying to find the best way to attack the problems, and provide the best solutions. It has long been an issue with me that tech answers should automatically feed back into documents, and then have a sunset so they go away after a suitable time when the docs now have the info (OK to have both for awhile).

That is my job (as a principal engineer) here at Xilinx: to be an agent for change (for the better). It is in my job description.

So, I really appreciate that you post (it directly helps me to fufill my job responsibilities), but if I don't have to go to the newsgroup to read it, it makes it even easier for me. OK if you don't. I am just asking (nicely).

Thanks for today's tough task, by the way.

As for "the answer" I can't do that in Spartan land, as I have no easy access to the chip schematics like I do for Virtex. If it was Virtex X+1, I just go to the schematics and dig for awhile. Sorry I can't do that for you on this one,

Austin

"rickman" schrieb im Newsbeitrag news: snipped-for-privacy@t31g2000cwb.googlegroups.com...

Rick

TDO is not is not full-time output (or at least doesnt have to be) TDO is driven when JTAG TAP is in 'shift' states and tri-stated otherwise so a pullup makes sense :)

Antti

I found the missing info. Instead of putting the details along with the other details in the pin descriptions, the pull ups are mentioned in the section header which I did not read. That seems to be the only info in the section header, the pull ups. The pins I was researching were on the following page and so the header was not apparent.

The confusing sentance still stands however. Whatever the words mean, I assume it is simply saying that there are pull up resistors on all of the configuration pins regardless of the state of the HSWAP_EN pin.

I don't know what to make of you Austin. You certainly don't come across as a people person. But thanks for the permission to post here. ;^)

Just FYI, I have to fight just as hard in the company where I work to get people to produce decent documentation. It's not that it should always be perfect... we're all human. But so many people don't feel documentation matters much. They think it is all about the product. But people's lives depend on our products and I am taking that very seriously.

As to this issue, it almost cost me a pointless board spin; not life threatening, but certainly that could be career threatening.

As to contacting Steve, I have done that. I hope that the pull up issue becomes more widely understood. The combination of poorly documented pull ups and the stiff value of these pull ups in the Spartan 3 devices can make a lot of trouble for a lot of designs.

Rick,

Well, I hope you keep up the comments.

I am seriously trying to improve the documentaion process.

If we explain it right the first time, we get less confusion, and we get to market faster.

Really very simple, and very self serving: the better the docs, the less time wasted, and the faster our customers either gain success, or fail. The faster money changes hands. The faster we succeed (or fail to succeeed).

It is so simple, yet so many (most) companies get it wrong.

Just make it simple to succeed, and don't get in the way, or make things any tougher than they already are.

As for my personality, my wife thinks I am completely impossible ('how can anyone work for you?'). My staff thinks I am the best boss they every had ('how can your boss deal with you?'). My supervisors love that I always come to them with a solution to the problem ('how do you keep your people so happy?'). My (totally grown) kids claim I am totally mad, and can not be trusted even for a moment ('that's not fair!'). My grandchildren sense I can be completely trusted to see to their well being and happiness (which I can be).

So, I have a personality: guilty as charged. Member of the human race.

Austin

Rick,

Thanks for the compliment.

Aust> As long as you brought up your personality, I'll just say that I

First, some background. On Spartan-3, the dedicated configuration pins, like CCLK, DONE, PROG_B, M2, M1, M0, and HSWAP_EN itself, all have an internal pull-up resistor to VCCAUX that is active during configuration, regardless of HSWAP_EN. After configuration, these pins have a bitstream generator option that defines their respective behavior.

All other pins have optional pull-up resistors, controlled by the HSWAP_EN pin. When HSWAP_EN=0, these pull-ups are enabled to their respective I/O Bank voltage supply (such as VCCO_0, VCCO_1, etc.).

What the who!?! I think the intention was that the "pull-up resistor connects to VCCAUX", _not_ HSWAP_EN. I'll see that we get that one fixed ASAP!

The updates happen periodically. As various issues are reported by the Xilinx Technical Support team, we update the documentation to make sure that you don't bump into any known landmines (okay, not a Marketing term). The latest updated changed maybe 0.1% of the verbage. We incorporate the latest learning, new ideas, and latest information. Believe me, we want to make your design experience as pleasant and trouble-free as possible.

I encourage active feedback. If something is confusing, please let us know, as it will likely be confusing to others. Most of our best product and documentation ideas come from Xilinx users! Feel free to E-mail me directly for Spartan documentation or use the Feedback link from the Xilinx web site.

--------------------------------- Steven K. Knapp Applications Manager, Xilinx Inc. General Products Division Spartan-3/-3E FPGAs

--------------------------------- The Spartan(tm)-3 Generation: The World's Lowest-Cost FPGAs.

You might also try educating your FAEs. I specifically asked my local FAE about using resistors to set the mode pins ("Why do the app notes show direct connections to Vcc and Gnd, will resistors work ok?") and he said that we could use 4.7 kohm resistors. Clearly this is not a correct answer. Based on his reply I almost commited to a design that would not have worked.

Like I said in my email, the info is mostly in the data sheet. But there are many places where it seems to contradict itself and is so scattered around that it would take a hour or more of intensive searching to find all the relevant info. I actually sat down earlier and did a search on "pull-up" trying to find all the info on the pullups and the configuration pins. Even then I missed a few items like the *only* place in the document where pull-ups on the mode pins are mentioned, in the header for the pin description section that covers the configuration pins.

I am asking that you not wait until a frustrated user reports your mistakes. I am asking that you have someone look at what it takes to find all the info that an engineer needs to configure these parts and make the info consistent and more usable.

Documentation by the designer is notoriously awful, but to start with, the designer is who is available. It takes a truly wonderful designer to put himself in the position of someone encountering his design for the first time. Just ask the people trying to use my documentation. Input from frustrated users is necessary. I don't have the information to know whether the documentation for this part is as good as it could be given the user input.

Wouldn't that depend on the designer???

No, it just takes someone who is familiar with the process of documentation. One of the big problems with documentation is that they let amateurs do it. By amateurs, I mean they teach designers how to design, but not how to document. I have worked places where the documentation was done by a separate group of documentation experts. They did not have the detailed technical knowledge of the designer, but they knew the process and had the designer as a resource to draw on.

Other companies are engineering focused and so document from the perspective of an engineer who often, by the time the documentation is being done, is getting tired of the program and doesn't like documentation anyway. The result is a poor document with little peer review (or review by peers who also don't get it).

Only necessary if produce poor documentation in the first place.

It is pretty obvious that they dropped the ball in a couple of respects. Even once the document was published, there were calls into support about some of the configuration issues which resulted in an answer record a year ago. Clearly someone at Xilinx knew that there was a shortcoming in the documentation to have produced this. But that shortcoming was never corrected in the data sheet. Lack of internal communication perhaps? One group pointing out a problem and another group in denial? I can't say. I just know I had a very hard time finding all the data on configuring the parts and I am still not sure I have it right.

Rickman -

I have no bones to pick with you and I should know better than to dive into this pissing match between you and Austin, but from your posts on this group you come of to me as a perpetually exasperated and pissed off person who is probably not a barrel of laughs to be around. Case in point is all of your ranting posts about those darn S3 pullups. I don't have a problem with you being a little pissy now and then, but I do have a problem with you taking shots at anyone else's personality. Those in glass houses, bro'. By the way, I disagree with your assessment of Austin's on-line personality. He gets passionate, but unlike you is almost always curteous (except with Leventis from Altera).

Rob

I was actually pleasantly impressed with how civil both parties have been in this discussion. It's tough being chewed at by anal design reviewers nitpicking every aspect of your design which requires an official point-by-point follow up afterward to maintain ISO9001 compliance. Yeesh!

I still haven't seen definitive answers for rickman's specific issue which should be able to be answered by the data sheet or supporting literature. It's a difficult situation for all parties involved.

I appreciate the restraint shown by all.

John,

I have no issues with Rick - I understand his frustration, and I share it. Please do not think poorly of him. Xilinx did not do him a service, and he feels compelled to share his experience here. OK. At least Steve got it, and fixed it (which is what counts). For every verbal complaint, there are at least ten others too busy to complain (a basic rule of customer support).

I am actively working every day to improve Xilinx communications to our customers because it is just darned good business to do so: faster it works, faster we get orders. Just that simple.

But, let us go back to history...

Napoleon was a great leader, and a visionary. Parks, forests, roads, and many other things people take for granted in Europe were done by his command. The fact that he lost his last battle has left him judged rather poorly by the English dominated history books. If he would have won, the books would vilify the losers!

History is written by the winners. A good historian recognizes this, and attempts to place themselves in the loser's shoes, and read all original accounts, and tries to feret out what facts they can.

To accuse me of being as arrogant as Napoleon was obviously designed to tweak my nose - I know that. But in the Zen tradition, I thank Rick for his gift of Napoleon, and appreciate it all the more for its wisdom.

Merci beaucoup M. Rickman, je vous remercie pour votre compliment.

Reflecting on world history,

Austin

"History will treat me kindly, for I intend to write it" Winston Churchill.

But I'm not sure the vilification of the loser was unjust that time.

Regarding Napoelon: France loves him, although he caused misery and the death of hundreds of thousands of her sons. The Germans hate him for beating their armies, although he also terminated the Middle Ages and laid the beginning of the foundation of the modern German state and its secular laws.

For better or worse, Napoleon left an enormous, and largely positive heritage. (I grew up in a house that Napoleon rode by on his way to Moscow... History is everywhere in Europe.) Peter Alfke

If they guy making development board for a part would not have access to anything except the datasheet, then maybe there would be improvements.

Documentation is improved if it can be measured against a standard on what the documentation should contain.

It's stunning how bad IC documentation is, and not just Xilinx. The use of the passive voice ("the enable input, when asserted..." Who the hell pulls it high, or maybe low, me or the chip?) and the persistant refusal to distinguish between levels and edges are two especially annoying lapses. The guys who do mixed-level stuff, like serial ADCs, are extra bad.

Who *writes* this stuff?

John