Review of Native Documentation (Part 1 - Comments)

[mikep]

I have reviewed the modified documentation for the native mode devices. I concentrated on chapter 4 and the Resource Usage section. I have the following comments:

• The comment on page 86 about issues of register allocation etc by the compiler are exactly the same as if you were writing C/ASM code yourself for the AVR. The answer is to apply the same techniques as you would when you are writing native C/ASM code yourself. Either way the item is beyond the scope and people should consult other sources.
• You may as well mention the clobbers mechanism for assembly cocde and as in the item above, then describe that this is an advanced topic and programmers should consult the same resources that they would if they were writing native C code.
• In the beginning of section 4.3 (on page 87) there is a hint about several ISRs not being available without naming them. This might be better moved and combined with the text on page 88 that describes exactly which ISRs are unavailable.
• It might be worth pointing out that ISRs do not get a z? prefix as they are standardized names declared in the GCC device .h files.
• The RESET ISR is missing from the list and presumably is reserved by ZBasic.
• It might be better to split the table of ISRs so that those that are not allowed are in a separate table. This would allow the removal of notes 2 and 8 so they can be replaced by some intro text (most of which is already written on page 88 before the ISR table).
• I would prefer the ISR notes (1,3,4,5,6,7,9) to be part of the ISR table by adding an extra column with the ZBasic API name. Some extra lines would need to be added to the table for differences across the rows.
• Need to add some text for ISRs that describes how to use the new subroutine "UpdateRTC".
• The comment on page 91 about inlined code being larger is not strictly true. I have found that inlined code can be smaller because register push/pops and call/returns are eliminated.
• On page 9 in the Resource Usage section, the list of routines that disable interrupts might be better described as the list of routines that have interrupts turned off during their execution.
• The table on page that lists the library routines that may load ISRs is an abbreviated form of the table on page 88 in the reference manual. It might be better to copy that table or eliminate the abbreviated one on page 9. USART_ISRS abbreviation makes it even hard to understand which ISRs apply to each platform.

[dkinzer]

I have the following comments [...]

Most of the points are well taken and have been incorporated.

The RESET ISR is missing from the list

Of course, the reset vector is fundamentally different from an ISR vector. In any event, it can't be overridden at all so it it is not mentioned. There are ways to write code to be executed at different points in the startup sequence. In anticipate writing an application note on this topic as well as some of the other topics not fully addressed in the two manuals.

Need to add some text for ISRs that describes how to use the new subroutine "UpdateRTC".

Inasmuch as an ISR should be written to execute in a very short amount of time, I can't imagine needing to update the RTC. If it is needed for an unusual case, you can invoke it (and Yield() for that matter) from an ISR just as you would anywhere else.

[mikep]

Of course, the reset vector is fundamentally different from an ISR vector. In any event, it can't be overridden at all so it it is not mentioned.

I thought you should mention this fact for completeness.

There are ways to write code to be executed at different points in the startup sequence. In anticipate writing an application note on this topic as well as some of the other topics not fully addressed in the two manuals.

I would like to see as much as possible covered in the manuals but I can see where certain topics like a tutorial could be done in an application note. Are you planning to use AN-3xx for native mode specific application notes?

Inasmuch as an ISR should be written to execute in a very short amount of time, I can't imagine needing to update the RTC.

Good point. Perhaps you need to reinforce that point in the documentation and that a ISR should definitely take much less than one RTC tick.