• State Resolved
  • Locked Locked
  • Replies 4 replies
  • Subscribers 98 subscribers
  • Views 409 views
  • Users 0 members are here
Support feedback
Options
Options
Related

This thread has been locked.

If you have a related question, please click the "Ask a related question" button in the top right corner. The newly created question will be automatically linked to this question.

C6678 SRIO documentation clarification

Peter Robertson
Expert 2770 points

In SPRUGW1B table 3-46 (LSU_Reg5 Field Descriptions) it states: "drbll Info: RapidIO doorbell field for type 10 packets".

Table 3-44 (LSU_Reg3 Field Descriptions) has: "Drbll_val": For Ftype != 10, 1 -> Doorbell information is valid".

Which of the following is meant:

A: The only way to send a doorbell interrupt is by using FTYPE=10.

B: An NREAD or NWRITE packet (Ftype 2 or 5) can send a doorbell interrupt on completion of the transfer. If so, is the LSU_Reg5 field used (if not, what is used), or, if not, what is the point of the Drbll_val field?

C: something else entirely.

Whatever the answer, the documentation is unclear and should be expanded.

  • 0
    TI__Mastermind 23525 points

    Peter,

    You can send a doorbell two ways:  1) you explicitly specify a ftype 10 packet using LSU_reg5.  You also fill out the other registers needed for the transfer with doorbell_info, SRCID, DESTID, etc...  2) instead of explicitly programming the LSU for a doorbell only, you can have the LSU send one automatically immediately after sending other data packets.  This method will reuse the same values for SRCID, DESTID, PRIORITY, etc. as the data transfer, then send the doorbell if DRBLL_VAL is set. It uses the doorbell_info field in this case too.

    If you feel the bit description for DRBLL_VAL is not sufficient, you can submit documentation feedback via the link on any page of the document.

    Regards,

    Travis

  • 0 in reply to tscheck
    Expert 2770 points

    Thanks for the explanation.

    As to providing feedback, that would be a full-time job, as TI's documentation is full of ambiguities, information scattered to the four winds, and obscure language. The point of documentation is to explain things clearly, but instead it is often rather like a cryptic crossword, where the solution is only obvious when your been told it. The documents have a bizarre mix of confusing brevity and pointless repetition (do you really need almost four pages of identical descriptions of RXU_MAP1_L, RXU_MAP2_L, ...? I am sure someone could come up with a more compact way of presenting that information).

    To give just three examples of problems from the SRIO document:

    1: The example I gave earlier, where "drbll Info: RapidIO doorbell field for type 10 packets" strongly suggests that this field is relevant only to type 10 packets when in fact, as you explain, it is also used in packets that have DRBLL_VAL set. Rarther than leave the ambiquity, wouldn't it satisfy the assumed aim of the document by changing the text to something like "drbll Info: RapidIO doorbell field for type 10 packets or other packets with DRBLL set in Reg3"? Or would that make it too easy for readers?

    2: Registers, such as ASBLY_ID, which are clearly marked as being read-only (and in this case, explicitly described as "hard coded and will not change from their reset state") yet have CSL functions to change them. Eventually one discovers that there is a class of register that is usually read-only but which can be written to under certain circumstances. Rather than leaving this as an exercise for the reader, why not have a category that explicitly states it, for example, by marking such registers as 'M'?

    3: The description of the "interrupt Req" (or is that "Int_req"?) bit in LSU Reg4 states "An interrupt is requested upon completion of command". Trying to work out which interrupt is a non-trivial task that involves searching through several sections of the document, and even then the answer isn't obvious.

    In all cases, and there are many, many more, once you've been told what is actually happening, things become obvious, but until then, even having read these large documents many times, it's all as clear as mud.

    Regards,

    Peter

  • 0 in reply to Peter Robertson
    TI__Mastermind 23525 points

    Peter,

    I understand your point of view, and apologize for the inadequacies in the documentation.  I'll forward your suggestions above to the appropriate folks.

    Regards,

    Travis

  • 0 in reply to tscheck
    Expert 2770 points

    As far as I can tell, and ignoring the inevitable errors which cannot be avoided, the failings of TI documentation are the result of one, very common mistake: all the documents have been written from the perspective of someone who fully understands the topic and wants to write down all the facts relating to the hardware and the software. This is always fatal to communication. Anyone who is too close to the hardware ends up assuming that many useful facts are so obvious that they are not worth writing down. Without those assumptions being made explicit, the documentation becomes impenetrable.

    Documents must be written from the point of view of someone who understands nothing about the topic (save the fundamentals of general computing). As a software engineer, I have zero interest in voltages, pin-outs and other things that are of interest to a hardware engineer. The hardware and software descriptions are better kept apart.

    Sticking with the SRIO document, once you have skipped the first 23 pages, which contain nothing of any use to an on-line reader, and skipping the next two pages of boilerplate, we hit what is essentially marketing blurb and mind-numbing detail of 1x/4x LP-Serial specification and interconnection information. In essence, Chapter 1 contains nothing that wouldn't be better placed in an appendix.

    Chapter 2 seems to be starting on something useful about actually using the device, but no. Instead of providing a clear and simple overview of how the device is used, it cannot resist diving into detail as soon as possible, talking about muilticast and Base Routing Registers and diagrams that are utterly meaningless until the reader understands the basics. At this stage, the reader hasn't a clue as to what's going on, yet the document concentrates on pin data rates and clock recovery and other stuff that, while interesting and useful in context, is completely out of place. Instead of starting simple to give readers a clear understanding of the general principles and then developing that with steadily increasing detail, the writer can't wait to get into minutiae. And so it continues.

    You see the same pattern in all TI documents, and the result is that TI has to produce more and more documents and answer countless questions to try to dig people out of the confusion that would never have been created if the base document had been written clearly with the reader in mind.

    By now you will be fully aware of my frustration. With each new TI document I have essentially to write my own manual, carefully extracting the relevant information and ordering it from the simple to the complex, separating out the hardware detail that is of not interest to someone trying to program the device. I usually end up with a very small document that makes everything obvious. If I can do it, why can't TI?