OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-sidsc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: NXP feedback on DITA SIDSC register specializations


Hi All,

 

Here’s the feedback on DITA SIDSC register specializations from Kathrin Hoffnagle, one of the tech authors (and XML hobbyist) in our microcontrollers group:

 

I looked through the SIDSC documents and compared the register description structure to the ARM® Cortex™ Microcontroller Software Interface Standard (CMSIS) register description. CMSIS is the register description standard we are using to map register information in xml to various outputs like the user manual, header files for application code, and tool-vendor specific graphical user interfaces, which are integrated in board development tools.

 

I am attaching an excel spreadsheet for you to see which SIDSC elements are present in CMSIS and how we are using any of these elements in documentation, that is in the NXP user manual template and the tool specific GUI called the system viewer or SFD file. CMSIS specs can be found on the internet.

 

To summarize, the structures of SIDSC and CMSIS register descriptions are very similar, and I think we could use SIDSC just as well as CMSIS. There are few things, where I think CMSIS is more straightforward for describing our chips (microcontrollers):

 

·         Register and component addressing is easier in CMSIS. Fewer nesting levels of elements are needed (e.g. no memory map, no address block container). The CMSIS approach works for us.

·         The description of reset values provides many more options in SIDSC. This could be useful, but at the moment we do not have any documentation template support for this and CMSIS just uses a simple reset value on the register level.

·         The access to bit fields is structured better in CMSIS and can be used on register or bit level. However, I have yet to implement this in a consistent way in our documentation.

·         CMSIS uses a few more container elements to structure the xml. I like it, but I am not sure whether this is really necessary.

·         Interrupts should be included at the component level.

 

We also need some way of marking register and register bit fields with an attribute  for being included or excluded in the documentation output. The registers that will be represented in user documentation are not necessarily the same as the original IP design. Some registers you don’t want the customer to see, but they need to be nonetheless included in the register description, so they can be tested in-house. Right now I would have to do some sort of preprocessing of the xml to accomplish this. Since the goal of SIDSC is to produce documentation for the customer, some means to filter the output from the original design would be nice to have. Maybe this is already there, I am not sure…

 

Also, eventually we should have some instructions for assembling all the IP into a device (a microcontroller e.g.), so there needs to be something above the component level.

 

On the DITA part, I can’t really comment. I assume, we at NXP would have to develop some way to display these DITA specializations in actual documentation. With CMSIS and FrameMaker, I can do quite a few things already, but it’s far from perfect.

 

The SIDSC and the SPIRIT formats are pretty compatible. I have thought about converting SPIRIT to CMSIS directly because we also created a set of SPIRIT files from our register descriptions, but I don’t quite have the tools and time to do so. Instead we start from a CSV representation and create either CMSIS or SPIRIT. The other thing is that there does not seem much enthusiasm about using an IP-XACT SPIRIT based design in our group.

 

However, I should point out that the SPIRIT description is used by other groups in NXP, and they also have Excel based register editors to go with that. I guess SPIRIT is more for the design side of things and CMSIS for the tool/application side.

 

Hope this helps!

 

Regards,

 

John Walker

Business Analyst, Corporate Communications and Branding

NXP Semiconductors

High Tech Campus (HTC)60 - 4.38c, 5656 AG Eindhoven, The Netherlands

Tel: +31 40 27 29187, Mobile: +31 613973664, Fax: +31 40 27 29961

E-mail: john.walker@nxp.com, www.NXP.com

 

The information contained in this message is confidential and may be legally privileged. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, dissemination, or reproduction is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.

 

OASIS SIDSC elements notes.xls



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]