TI Glossary could be improved

Ok,
I found the imformation about TIMESYNC and CMP in TRM, section 10.3.1 Time Sync Architecture.
Nevertheless a description column saying something like

| Interrupt Router Device Name        | Interrupt Router Device ID | Description                                      |
| ----------------------------------- | --------------------------:| ------------------------------------------------ |

| AM64X_DEV_CMP_EVENT_INTROUTER0      | 1                          | Active counter compare events                    |

                                                                    (see TRM, section 10.3.1 Time Sync Architecture)

| AM64X_DEV_TIMESYNC_EVENT_INTROUTER0 | 6                          | Synch master                                     |

                                                                                                                                                          (see TRM, section 10.3.1 Time Sync Architecture)

Could have saved me quite some time figuring out where to look.

Best

Philip.

P.S. I tried to use the tables provided in the toolbar in the edit view on the bottom, but they didn't appear on my post and I couldn't set a special header row.
So I am providing the table in markdown.

Hello Philip,

Thanks for the feedback. There are a lot of IPs in our processors and in the software files, and not everything is well defined.

This is a pretty broad challenge. So let's break it down and see if we can make progress on specific parts.

Preprocessor register defines
Preprocessor register defines in the CSL code are auto-generated from the register names and bitfields. So if the register name or bitfield name is cryptic, there's not really anything we can do to change the register defines. Register names are usually specific to an IP in a processor, so they are often too specialized to go in the TI Glossary.

Interrupt routing
This in particular has pretty confusing documentation at this point in time. We are working on cleaning up at least some of the documentation, but specific feedback is helpful. You can find more information about the Time Sync Router (and limitations of the current HW docs & SW) at this FAQ: https://e2e.ti.com/support/processors-group/processors/f/processors-forum/1061474/faq-am64x-what-is-the-time-sync-router-for-how-do-i-use-it

Next Steps
ok, given that information: Where would you like me to route your thread? e.g., for TI Glossary there is a link to submit documentation feedback on the bottom of each page, or we can see if the folks who own the TI Glossary are on e2e for comment. Or if you want to follow-up on AM64x specific feedback, I can route you to the appropriate HW documentation or SW teams. etc.

Regards,

Nick

Hello Nick,
thank you for getting back to me.
Just a question to better understand your comment.
Not sure if you did that to make my point :), but you are often using the term "IP".
Do you mean "intellectual property"?
Because IP means to me something like 192.168.23.42 .
This is a good example of "Please spell out abbreviations at least once before using them."
I read the term before in TI texts, and I asked my friend Google what that could be, since "Internet Protocol" made no sense.
Thank you for clarification.


Best regards

Philip.

Hello Philip,

Fair point!

A processor is a black plastic package with metal balls or leads that allow signals to enter and exit the package. Inside that package is a bunch of circuitry. Different groups of circuits make up different parts of the processor - e.g., one group of circuits is the A53 cores, one group is the time sync router, one group is the PRU_ICSSG, etc. I do not know if this is an industry standard (or if it is even written down anywhere in our docs), but in verbal conversations we call a bunch of circuits that do a specific thing an "IP" (e.g., the USB peripheral is an IP). So a processor is a bunch of different IPs that have been put together within the same package.

Regards,

Nick

Hello Nick,
thank you for the explanation.
While you have explained everything thoroughly, your explanation still doesn't say what the abbreviation IP stands for.
I guess it is this:

en.wikipedia.org/.../Semiconductor_intellectual_property_core

Anyway, let's not get stuck on that one.

Another example that I came accross just now would be this:

http://downloads.ti.com/tisci/esd/18_08_00/2_tisci_msgs/rm/rm_udmap.html

Here it tells me a lot about how I can configure UDMAP channels and whatnot.
But in the beginning a short sentence would have been nice to tell me, what UDMAP means at all.

As I said I am currently in the process of abstracting interrupts. So I went on the page for the IRQ resource management.
And simply looked at a few pages that were in the context of resource management to see if they might be relevant to me, and found this one.

To me it was unclear if it has something todo with Ultra Direct Memory Access (UDMA) and then something starting with P, that I don't know. Or if it was some map of something abbreviated by UD.

I didn't find the abbreviation in the TRM nor in the AM64x Datasheet.
By chance I found in the UDMA section of the datasheet that there is a peripheral UDMA controller, called UDMA-P.
But since the webpage said UDMAP, I didn't look for UDMA-P and therefore didn't find anything about the term UDMAP.

Had you started this page:

http://downloads.ti.com/tisci/esd/18_08_00/2_tisci_msgs/rm/rm_udmap.html

instead of with

"This chapter provides information on usage of the RM UDMAP management TISCI message API parameters."

with something like

"This chapter provides information on usage of the RM TISCI message API parameters for the peripheral UDMA controller (UDMA-P) (see AM64x Datasheet, section "PDMA Controller" for details)."

I could have saved quite some time finding out what it was.
Thank you.


Best regards

Philip.

Hello Philip,

We have a pretty big team here. It sounds like you want to give feedback on TISCI docs first. I am not the right guy to make changes to the TISCI docs, so give me some time to figure out who the right person is. If I have not responded within a couple of business days, please ping the thread.

Regards,

Nick

Hello Nick,
I am certain, that you have a big team.
It is just that I cannot give examples that are not in a specific area.
This example was from the TISCI documentation, but please don't try to pin me down on TISCI only because that example by chance tended to be from TISCI.
I found the same pattern in the TRM, the datasheet, several online documentations
and other things. At many places there are abbreviations used that are not spelled out before.
And at least for me it takes quite some time to find out what the stuff is about at all, because the main term eludes me.

It is exactly the example that we had in the beginning. You said that the IP term is something that you use regularly in your company.
Now all I am asking for is to take care when writing the documentation, not the TISCI documentaiton but any documentation, that you or anyone writing documentation takes into account that only because in your company people know what the terms they use internally mean doesn't mean that outsiders know it. That is all.
My hope is that when you do that the documentation will clear itself up over time.
Thank you very much.


Best regards

Philip.