Emitting debug info for tinsel elf files

[m8pple]

In order to work out how and where instructions are being spent, it is useful to have debug information in the tinsel elf files.

It's possible this is supported, but I couldn't work out a way of doing this.

Things tried were:

• Reading the documentation for "compose" in head branch of https://github.com/POETSII/orchestrator-documentation/blob/development/source/user_guide.md
• Searching for the string "debug" in orchestrator-documentation

Nothing explicit came up. Some possibilities seemed like:

• Building the Orchestrator using "make debug". However, this seemed more like a developer thing than a user thing.
• Passing options to the compiler via "composer /arg". This seemed more promising, as it seemed like I could pass "-g" in.

I read the documentation on parameters and clauses in the user guide, and based on that tried:

composer /args = "-g" /app = *

which gave the error:

POETS> 14:48:50.13: 173(W) Unable to find application '-g'. Not operating on any applications.

Thinking may be the clauses need to be ordered (?), I tried:

composer /app = * /args = "-g" 

This seemed to run the composer once (successfully), but then run it again with just the args clause, which fails:

POETS> 14:55:35.10: 302(I) Graph instance 'blurble' placed successfully.
POETS> 14:55:36.13:  20(I) The microlog for the command 'compose /app = *' will be written to '../Output/Microlog/Microlog_2021_12_28T14_55_35p5.plog'.
POETS> 14:55:36.13: 803(I) Composing graph instance 'blurble'...
POETS> 14:55:36.13: 804(I) Graph instance 'blurble' composed successfully.
POETS> 14:55:36.13:  20(I) The microlog for the command 'compose /args = -g' will be written to '../Output/Microlog/Microlog_2021_12_28T14_55_36p0.plog'.
POETS> 14:55:36.13: 173(W) Unable to find application '-g'. Not operating on any applications.

Maybe the syntax should be something else? I tried the example given of "echo", and it seemed to work fine:

POETS>test /echo = "A" /echo = "B"
POETS> 15:03:28.59:  23(I) test /echo = "A" /echo = "B"
POETS> 15:03:28.59:  20(I) The microlog for the command 'test /echo = "A" /echo = "B"' will be written to '../Output/Microlog/Microlog_2021_12_28T15_03_28p0.plog'.
POETS> 15:03:28.59:   1(I) A
POETS> 15:03:28.59:   1(I) B

So this started as an issue about debug info, but I guess it turns into two:

• How does one pass multiple clauses to a command. Maybe an example of using composer params in the docus would help.
• How can debug info be embedded into the tinsel elf to help understand instruction sizes.

I wonder whether it would be worth just adding "-g" to the build steps for the elf binaries by default.

[heliosfa]

composer /args = "-g" /app = *

This is equivalent to issuing two separate Compose commands and the args command is incomplete because it is missing the application specifier.

Try compose /args = *,"-g" (before compose /app = *) - this adds the specified flag(s) ("-g" in this case) to the specified apps (all in this case). Syntax is in the big table on P.34 of the Composer docs (Vol III(b)).

How does one pass multiple clauses to a command. Maybe an example of using composer params in the docus would help.

You are using the correct syntax to pass multiple clauses, but you need to be passing multiple parameters for the /args clause. The syntax for doing this in the general case is discussed in the "Commands, Logging, and I/O" section of the user docs (section 4.1.3 in the release PDF).

The specific use for the Composer's args clause is shown in section 5.1 of the Composer docs.

I'll agree that it is not clear in the userguide which clauses take multiple parameters, but I have always been under the impression that the userguide is not meant to be a full, comprehensive command syntax list as our (fragmented...) docs setup would result in a lot of duplication between files that would be a pain to maintain. I'll have a think about how to indicate this generally without being overly syntax-specific. Any thoughts?

I wonder whether it would be worth just adding "-g" to the build steps for the elf binaries by default.

Doesn't g come with a performance overhead? I know it comes with a size overhead (which could be problematic in the default case) so I would be wary of just enabling it.

Happy to add a specific composer clause for enabling debug symbols in emitted binaries if it would be more convenient.

[m8pple]

Try compose /args = ,"-g" (before compose /app = ) - this adds the specified flag(s) ("-g" in this case) to the specified apps (all in this case). Syntax is in the big table on P.34 of the Composer docs (Vol III(b)).

Ah, ok - I couldn't work out whether "/args" was like a modal setting that happened before the actual command or something passed along-side the command, as I couldn't find any examples of doing it in the user guide.

The suggested command worked perfectly, thanks.

I'd read the documentation in section 4.1.3, but couldn't really work out what it meant. I think I read this "Note that each clause “invokes” the command once (there are three “1” messages), with each parameter passed to it.", but didn't understand it. I think I was too tied to the idea that a "command" is a distinct imperative action, while a "clause" is something that modifies the action.

I guess this is rooted in the grammatical idea of a "clause" (according to Wikipedia), but I went to a state school, so we weren't taught that. Plus I was crap at English.

I'll agree that it is not clear in the userguide which clauses take multiple parameters, but I have always been under the impression that the userguide is not meant to be a full, comprehensive command syntax list as our (fragmented...) docs setup would result in a lot of duplication between files that would be a pain to maintain. I'll have a think about how to indicate this generally without being overly syntax-specific. Any thoughts?

I was under the opposite impression :) I thought the pdf docs were the Orchestrator internals for developers, and the user guide was the user-facing part.

The pdfs have the titles:

• POETS Orchestrator architecture, Design Notes
  • Volume I - Introduction
  • Volume III - Orchestrator internals
  • Volume III(B) – On Softswitches, the Supervisor and Composer: Bridging the gap to the Orchestrator

In Volume I it talks about Volume IIII, which is supposed to be "The Orchestrator (user-facing) User documentation, and its interaction with the Orchestrator internals", but I don't think I've ever seen that. So I assumed the "user_guide" markdown document (and generated pdf) had replaced that.

Doesn't g come with a performance overhead? I know it comes with a size overhead (which could be problematic in the default case) so I would be wary of just enabling it.

There should be zero overhead in the size of the actual binary, AFAICT. However, making it an optional thing via -g is fine too, as I haven't verified that.

[m8pple]

BTW - don't feel the need to answer these right away, as I assume you are on holiday. I am just doing this at odd moments when I have time for "fun". I am now being pestered to go and help build Lego.

[heliosfa]

as I assume you are on holiday

What is holiday to an academic? I have actually been looking at this paper as a break from family!

I'd read the documentation in section 4.1.3, but couldn't really work out what it meant.

Yeah, the whole command interface is a bit esoteric and I think we need to clarify things. One for the todo list @mvousden !

Just to clarify the multiple clause/command/parameter thing, if you executed 'compose /args = ,"-g" /app = ' as one "command", it would set the arguments and trigger a compose as though 'compose /args = ,"-g"' and 'compose /app = ' had been called as separate commands. e.g. you can have multiple actions in response to one command, with the execution order dependent on the order they are defined in the command.

I was under the opposite impression :) I thought the pdf docs were the Orchestrator internals for developers, and the user guide was the user-facing part.

I guess there is some grey area on what needs to be where. Ultimately there is the concept of "basic" commands that a user will need to get a problem running on POETS, and then there are more "advanced" commands that a more advanced user may find useful to control things. I'd argue that the ability to turn on debugging symbols to be able to analyse the binaries is more of an advanced feature that not every user will need?

Also, is g not made next to useless as we compile with O2 or O3? Or is it only when debugging that it is a problem?

[mvousden]

So there's a lot going on here. Here's my attempt at understanding this issue, and a bit of my own thoughts:

Using multiple operator parameters with compose /args

• DBT is trying to pass -g to the Softswitch compilation.
• The correct way to do this, as the operator, is to command compose /args = *,"-g" to stage the flag for all applications (using wildcard * syntax), and then to compose the application by commanding compose /app = *.
• This could be made clear by modifying the compose command set in the user guide (perhaps to mirror the placement /constraint format?)

Softswitch compilation more generally

• DBT suggests adding -g to the softswitch compilation as a default flag. My take on this is that this is not so useful when -O3 is involved, but I'm happy for examples/smarter people to show me otherwise.

Clauses with multiple operator parameters more generally

• DBT is also confused about how to pass multiple operator parameters to a clause.
• This is explained in the documentation, where it says

Multiple parameters can be passed to a given clause (Command /Clause = Operator0Parameter0, Operator1Parameter1)

• This could be made clearer, perhaps by saying that test /echo = "apple" /echo = "banana" is identical to test /echo = "apple followed by text /echo = "banana"?

Documentation volumes

There's some confusion about Orchestrator volumes. My understanding is that they are:

1. is a very general overview of POETS, with a bit of an Orchestrator bend to it.
2. is the application definition, which explains how applications are formed, keywords, etc. (identical to applications.pdf)
3. is a collection of documents, which currently includes:
   • addresses.pdf
   • hardware_description_file_and_reader.pdf
   • hardware_model.pdf
   • launcher.pdf
   • mothership_design.pdf
   • Orch_Vol_IIIB_Softswitches_Supervisor_and_Composer.{pdf,docx}
   • Orch_Vol_III.{pdf,doc}
   • Packet_Format.{pdf,docx}
   • placement.pdf where Orch_Vol_III is the "main" document, and the other documents branch off it.
4. is the user guide (identical to user_guide.pdf).

Volume 2 lists every command an operator can run (aside from a few hidden test commands, which use undocumented functionality). This listing tersely explains what each command does, ideally without diving into the underlying structures used by the Orchestrator internally. If there's greater complexity behind any of these commands, they are listed in their equivalent volume 3 document.

[m8pple]

It would be useful if the documents in the release reflected that structure, as from a users point of view, if they look at the releases page (https://github.com/POETSII/orchestrator-documentation/releases/tag/1.4.0), there appear to be two classes of things:

• Orchestrator volumes, prefixed by "Orch_Vol_NUMBER"
• Other things, which are not orchestrator volumes and are some other kind of documentation.

I'd never realised that "user_guide.pdf" was supposed to be Volume IV, and "applications.pdf" was volume II, as the markdown on github is much more convenient to use than the pdf, and the title is very easy to overlook as compared with the section title "Overview".

If all the non-prefixed files are supposed to be Volume III, except for user_guide.pdf which is Volume IV, and applications.pdf which is Volume II, then it would help to have the pdfs in the releases reflect that in their filenames.

If the expectation is that users will only use the pdfs and not use the markdown, it would help to merge the various parts of Volume III into a single document, so that users only have one pdf per volume.