PLEA TO TI ENGINEERS re Starterware (referring to starterware directory [and other directories] in Processor SDK v3.0) Documentation:
I see the abundance of "docs" directories under Starterware and other directories in the PDK, which mostly contain Doxygen-generated documentation from the source code. However, the Doxygen documentation loses me in an abyss of details and provides, literally, ZERO orientation (a.k.a. answering question such as "What is in each directory and how are these pieces designed to work together as a whole?" (Something more current than training.ti.com/.../ which is now several versions old and quite out of date.) Such orientation material would answer the question (as an example), "What is that DAL directory and when and where do I need it in my custom application?" An example question that I am consuming a LOT of time on right now is: there is an LCD Controller example in here. It is using some sort of local high-level driver (local to the project) that eventually uses the LCDC.C functions in the DAL library -- yet I am writing a TI-RTOS application that needs extensive LCD support, and I'd prefer not to have to write my own LCD controller driver. Is this how I should be managing the LCD controller??? Via DAL library? CSL? Higher level? Most pertinent question to answer: What is the designer's intention for my situation?
While Doxygen provides an elegant means of providing such ORIENTATION / OVERVIEW documentation (referring to the \mainpage, \page, \subpage, \section, \subsection, \subsubsection, and \dir commands) no one (and I mean no one) has provided any OVERVIEW and ORIENTATION material in these AM335X Processor SDK "docs" directories, and it would be a GODSEND and worth GOLD if someone would fill in this missing data this way -- if they had done so, then I would be looking in the Doxygen documentation instead of coming to E2E to ask questions (and costing both of us time).)
Seriously: no disrespect intended -- I know in a team there are both growing pains and little things get dropped between the cracks. However, I am officially stating that this would be an outstanding (very, very valuable) service and a would create a MAJOR WIN-WIN situation (permitting engineering teams like mine to adopt TI hardware a great deal more easily) if whoever is already writing the Doxygen documentation in the source code files would be directed to address this ORIENTATION / OVERVIEW problem (in most cases, it is completely missing) in TI's usual top-professional manner.
Also, doxygen (with a certain graphics application installed, and with a list of include directories) is capable of generating dependency trees, and other relevant graphs, that is, up to this point virtually unused in these generated HTML files in the "docs" directories. Right now a dependency graph for the LCDC.C driver in the DAL folder would be an outstanding piece of information for the project that I am working on currently. I'll figure it out, but it would save me a lot of time to have that information as I write this -- using this as an illustration.
If you need a specific example (among dozens), there is the CSL library: <pdk>\packages\ti\csl\docs\doxygen\html\index.html If you pretend you don't know anything about the CSL library and have never seen it before (my situation), and think of a question, and try to find your answer in there, you will see that the (completely missing) orientation material makes it virtually impossible to discover the answer to your question (e.g. When do I need to use the CSL library?), and having this OREINTATION / OVERVIEW material would be a VAST improvement. It should be written to an audience that is just discovering the CSL library and need to know A) where it fits in the scheme of things, B) if he ever needs to use it directly and if so under what circumstances (i.e. what problems can be solved by using the CSL library directly), and C) a sort of a decision tree to know where to go in these directories to find the functions and data required to manage the _______ module in the AM335x (e.g. LCD Controller, Touch controller, PRUs, etc. etc.).
Respectfully yours,
Vic Wheeler
