Create itm.md #413

marcuschangarm · 2018-02-15T00:41:52Z

Documentation for the new ITM HAL API: ARMmbed/mbed-os#5956

marcuschangarm · 2018-02-15T00:42:17Z

0xc0170 · 2018-02-15T12:30:27Z

docs/reference/contributing/target/itm.md

+```
+#include "SerialWireOutput.h"
+
+FileHandle* mbed::mbed_override_console(int fd) {


style update

FileHandle *mbed::mbed_override_console(int fd) { }

Copy edit file for active voice, American English and precise language.

AnotherButler

@marcuschangarm Thanks for the PR. Please address my comments and queries.

AnotherButler · 2018-02-15T21:31:16Z

docs/reference/contributing/target/itm.md

@@ -0,0 +1,34 @@
+### Instrumented Trace Macrocell


Does this API have spaces in it, or does it follow the same formatting as the others ("InstrumentedTraceMacrocell")?

I don't understand the question. Instrumented Trace Macrocell is the name of the module like Low Power Ticker.

We have the ResetReason API, which is has no space and both Rs capitalized because we're referring to the class. Is it the same with this?

Ah, no. This is a physical component defined in the architecture: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0314h/Chdegecg.html

@marcuschangarm - Looks good, it would be great if you can add that ITM link in the documentation itself. Its not a blocker though, so I'll approve.

AnotherButler · 2018-02-15T21:32:58Z

docs/reference/contributing/target/itm.md

+##### Undefined behavior
+
+- The debug clock frequency is left undefined because the most optimal frequency varies from target to target. It is up to each target's owner to choose a frequency that doesn't interfere with normal operation and that the owner's preferred debug monitor supports. 
+


Query: Why are there no notes, dependencies or implementations? Please complete these sections.

AnotherButler · 2018-02-15T21:35:08Z

docs/reference/contributing/target/itm.md

+##### Defined behavior
+
+- Targets must implement the function `void itm_init(void)` and add `ITM` to the `device_has` section in `target.json`.
+- When `void itm_init(void)` is called, the debug clock for the ITM must be initialized and the SWO pin configured for debug output.


Query: Who or what is calling that function? Also, who or what is initializing the debug clock for the ITM and configuring the SWO pin for debug output? You, the user, or something else?

marcuschangarm · 2018-02-15T23:01:59Z

@AnotherButler I've reorganized the text and added the missing sections based on the other document you showed me!

bulislaw

One thing we need to add, once the doxygen is regenrated for master, is link to the API doxy.

marcuschangarm · 2018-02-16T23:11:22Z

The PR just got merged! Who can pull the doxygen lever? 😄

bulislaw · 2018-02-26T15:38:54Z

@AnotherButler can :)

Copy edit for active voice, consistent tense and proper formatting.

AnotherButler

I've left some comments and queries for you to address.

AnotherButler · 2018-02-28T19:57:31Z

docs/reference/contributing/target/itm.md

+
+##### Defined behavior
+
+When initialized, writing data to the ITM stimulus registers results in the data being transmitted over the SWO line.


Query: When what is initialized, by whom or by what?
Query: Who or what transmits the data over the SWO line? The ITM?

AnotherButler · 2018-02-28T19:58:38Z

docs/reference/contributing/target/itm.md

+#### Implementing the ITM API
+
+- You must implement the function `itm_init`. When the function is called:
+  - The debug clock for the ITM must be initialized.


Query: Do you, the user initialize the debug clock for the ITM?

AnotherButler · 2018-02-28T19:58:55Z

docs/reference/contributing/target/itm.md

+
+- You must implement the function `itm_init`. When the function is called:
+  - The debug clock for the ITM must be initialized.
+  - The SWO pin must be configured for debug output.


Query: Do you, the user, configure the SWO pin for debug output?

marcuschangarm · 2018-03-01T20:32:05Z

I think that should address the ambiguity? 😄

Copy edit for consistent tense and brevity.

AnotherButler · 2018-03-05T23:03:11Z

@bulislaw Do we already have a Doxy branch for this?

AnotherButler · 2018-03-13T15:16:37Z

@marcuschangarm Because this has merged into master, it should be in the generated Doxy: https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/annotated.html

However, I don't see it here. Could you please help me find it? Or check the mbed-os exclusions if it's not there?

marcuschangarm · 2018-03-13T15:59:29Z

I don't see it either - but there seems to be a lot of weirdness on those auto generated pages.

AnotherButler · 2018-03-29T21:59:08Z

@SenRamakri Can you please help with this?

SenRamakri · 2018-03-29T23:43:37Z

docs/reference/contributing/target/itm.md

@@ -0,0 +1,34 @@
+### Instrumented Trace Macrocell


@marcuschangarm - Looks good, it would be great if you can add that ITM link in the documentation itself. Its not a blocker though, so I'll approve.

AnotherButler · 2018-04-03T15:28:51Z

I need to make sure this is in the Doxy and include a link to the Doxy before merging.

AnotherButler · 2018-04-16T14:51:55Z

@SenRamakri Could you please help me find this in the Doxy?

AnotherButler · 2018-05-22T23:09:56Z

Note to self: @SenRamakri helped me find link: https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/group__itm__hal.html

Add missing link.

Create itm.md

c78bcd7

Documentation for the new ITM HAL API: ARMmbed/mbed-os#5956

marcuschangarm mentioned this pull request Feb 15, 2018

[feature-hal-itm] Instrumented Trace Macrocell HAL API for SWO debug output ARMmbed/mbed-os#5956

Merged

0xc0170 reviewed Feb 15, 2018

View reviewed changes

Complete initial copy edit of itm.md

adab5a4

Copy edit file for active voice, American English and precise language.

AnotherButler reviewed Feb 15, 2018

View reviewed changes

AnotherButler requested a review from bulislaw February 15, 2018 21:36

Added missing sections to itm.md

0ac6a71

AnotherButler added the code dependency label Feb 15, 2018

bulislaw approved these changes Feb 16, 2018

View reviewed changes

AnotherButler removed the code dependency label Feb 28, 2018

Copy edit itm.md

fdb4638

Copy edit for active voice, consistent tense and proper formatting.

AnotherButler reviewed Feb 28, 2018

View reviewed changes

Add more details to itm.md

4eb983d

Copy edit itm.md

e3df420

Copy edit for consistent tense and brevity.

SenRamakri approved these changes Mar 29, 2018

View reviewed changes

Add link to itm.md

9f098e2

Add missing link.

AnotherButler approved these changes May 22, 2018

View reviewed changes

AnotherButler merged commit 7159658 into ARMmbed:new_engine May 22, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create itm.md #413

Create itm.md #413

marcuschangarm commented Feb 15, 2018

marcuschangarm commented Feb 15, 2018

0xc0170 Feb 15, 2018

AnotherButler left a comment

AnotherButler Feb 15, 2018

marcuschangarm Feb 15, 2018

AnotherButler Feb 15, 2018

marcuschangarm Feb 15, 2018

SenRamakri Mar 29, 2018

AnotherButler Feb 15, 2018

AnotherButler Feb 15, 2018

marcuschangarm commented Feb 15, 2018

bulislaw left a comment

marcuschangarm commented Feb 16, 2018

bulislaw commented Feb 26, 2018

AnotherButler left a comment

AnotherButler Feb 28, 2018

AnotherButler Feb 28, 2018

AnotherButler Feb 28, 2018

marcuschangarm commented Mar 1, 2018

AnotherButler commented Mar 5, 2018

AnotherButler commented Mar 13, 2018

marcuschangarm commented Mar 13, 2018

AnotherButler commented Mar 29, 2018

SenRamakri Mar 29, 2018

AnotherButler commented Apr 3, 2018

AnotherButler commented Apr 16, 2018

AnotherButler commented May 22, 2018

		##### Undefined behavior

		- The debug clock frequency is left undefined because the most optimal frequency varies from target to target. It is up to each target's owner to choose a frequency that doesn't interfere with normal operation and that the owner's preferred debug monitor supports.


		##### Defined behavior

		When initialized, writing data to the ITM stimulus registers results in the data being transmitted over the SWO line.

Create itm.md #413

Create itm.md #413

Conversation

marcuschangarm commented Feb 15, 2018

marcuschangarm commented Feb 15, 2018

Choose a reason for hiding this comment

AnotherButler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcuschangarm commented Feb 15, 2018

bulislaw left a comment

Choose a reason for hiding this comment

marcuschangarm commented Feb 16, 2018

bulislaw commented Feb 26, 2018

AnotherButler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcuschangarm commented Mar 1, 2018

AnotherButler commented Mar 5, 2018

AnotherButler commented Mar 13, 2018

marcuschangarm commented Mar 13, 2018

AnotherButler commented Mar 29, 2018

Choose a reason for hiding this comment

AnotherButler commented Apr 3, 2018

AnotherButler commented Apr 16, 2018

AnotherButler commented May 22, 2018