• z80-asm-meter.statusBar.alignment: Controls the status bar item position:

  • leftmost: Leftmost position of the status bar.
  • left: Left side of the status bar.
  • right (default): Right side of the status bar.
  • rightmost: Rightmost position of the status bar.

• z80-asm-meter.statusBar.showInstruction: Shows the processed instruction in the status bar. Useful to check if the extension is mistaking instructions.

  Disabled by default.

• z80-asm-meter.statusBar.instructionIcon: The icon to identify the instruction in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(code).

  

• z80-asm-meter.statusBar.timingsIcon: The icon to identify the timings in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(watch).

  

• z80-asm-meter.statusBar.totalTimings: Shows total timing calculations in the status bar.

  See Total timing calculations for details.

• z80-asm-meter.statusBar.totalTimingsOrder: Determines the order of the total timing calculations in the status bar when more than one total timing calculation is visible.

  See Total timing calculations for details.

• z80-asm-meter.statusBar.sizeIcon: The icon to identify the size and the bytes in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(file-binary).

  

• z80-asm-meter.statusBar.sizeNumericFormat: The numerical format of the size in bytes in the status bar.

  • decimal (default): Size in bytes as a decimal number.
  • hexadecimal: Size in bytes as an hexadecimal number.
  • both: Size in bytes as both a decimal and an hexadecimal number.

• z80-asm-meter.statusBar.sizeHexadecimalFormat: The hexadecimal format for the hexadecimal size in bytes in the status bar.

  • hash: Hexadecimal size in bytes in hash format (#b45d).
  • motorola (default): Hexadecimal size in bytes in Motorola format ($b45d).
  • intel: Hexadecimal size in bytes in Intel format (0b45dh).
  • intelUppercase: Hexadecimal size in bytes in Intel format, uppercase suffix (0b45dH).
  • cStyle: Hexadecimal size in bytes in C-style format (0xb45d).
  • uppercaseHash: Hexadecimal size in bytes in uppercase, hash format (#B45D).
  • uppercaseMotorola: Hexadecimal size in bytes in uppercase, Motorola format ($B45D).
  • uppercaseIntel: Hexadecimal size in bytes in uppercase, Intel format, lowercase suffix (0B45Dh).
  • uppercaseIntelUppercase: Hexadecimal size in bytes in uppercase, Intel format (0B45DH).
  • uppercaseCStyle: Hexadecimal size in bytes in uppercase, C-style format (0xB45D).

• z80-asm-meter.statusBar.sizeSuffix: The suffix for the size in bytes in the status bar. Either a single string (such as " B"), or a couple of strings separated by pipe (|) for singular and plural.

  Defaults to " byte| bytes".

• z80-asm-meter.statusBar.showBytes: Shows the bytes (opcode) in the status bar.

  Disabled by default.

• z80-asm-meter.statusBar.copyTimingsAsHints: Enable copying timings as timing hints, instead of the default human-readable format.

  Disabled by default.

• z80-asm-meter.statusBar.debounce: Milliseconds to prevent metering from being called too frequently when the selection changes.

  Defaults to: 200 (200 ms).

• z80-asm-meter.statusBar.cacheSize: Size of the cache, in selections, used to minimize metering calculations when navigating through previously metered code.

  Defaults to: 200 (200 selections).

• z80-asm-meter.syntaxFeature.labelColonOptional: Adjusts the label detection to match the syntax of the assembler.

  When disabled, the labels must be followed by a colon (:) and can be indented. This behaviour matches most assemblers and coding styles.

  When enabled, the trailing colon is optional, and the labels must not be indented. This behaviour matches some assemblers such as Pasmo and SjASMPlus.

  Enabled by default when the main syntax of the assembler is set to pasmo or sjasmplus, disabled by default otherwise.

• z80-asm-meter.syntaxFeature.repeat: Enables support for parsing repeat count:

  • none (default): Disables repeat count.
  • brackets: The repeat count is specified within square brackets ([ and ]) before the instruction. This behaviour partially matches the source format of Sjasm, but multiple repeat counts and iteration count are not supported. This is the default value when the main syntax of the assembler is set to sjasm.
  • dot: The repeat count is specified after a dot (.) before the instruction. This behaviour partially matches the repeat pseudo-op of SjASMPlus, but multiple repeat counts and expressions are not supported. This is the default value when the main syntax of the assembler is set to sjasmplus.

• z80-asm-meter.syntaxFeature.lineSeparator: Adjusts the line separator to match the syntax of the assembler:

  • disabled (default): Does not allow multiple instructions on a single line.
  • backslash: Use backslash (\) to have more than one instruction on a line. This behaviour matches some assemblers such as SPASM-ng. This is the default value when the main syntax of the assembler is set to spasm-ng.
  • colon: Use colon (:) to have more than one instruction on a line.
  • pipe: Use pipe (|) to have more than one instruction on a line. This behaviour matches some assemblers such as tniASM. This is the default value when the main syntax of the assembler is set to tniasm.

• z80-asm-meter.syntaxFeature.fakeInstructions: Enables SjASMPlus fake instructions support.

  Enabled by default when the main syntax of the assembler is set to sjasmplus, disabled by default otherwise.

• z80-asm-meter.syntaxFeature.registerListInstructions: Enables SjASMPlus register list instructions support.

  Enabled by default when the main syntax of the assembler is set to sjasmplus, disabled by default otherwise.

• z80-asm-meter.syntaxFeature.negativeConditions: Enables Glass negative conditions) support.

  Enabled by default when the main syntax of the assembler is set to glass, disabled by default otherwise.

• z80-asm-meter.syntaxFeature.dupEdup: Enables DUP/EDUP repetition blocks.

  Enabled by default when the main syntax of the assembler is set to sjasmplus, disabled by default otherwise.

• z80-asm-meter.syntaxFeature.reptEndr: Enables REPT/ENDR repetition blocks.

  Enabled by default when the main syntax of the assembler is set to sjasmplus, disabled by default otherwise.

• z80-asm-meter.syntaxFeature.reptEndm: Enables REPT/ENDM repetition blocks.

  Enabled by default when the main syntax of the assembler is set to glass, disabled by default otherwise.

As a summary, these are the default values of the assembler syntax settings, based on the value of the main z80-asm-meter.syntax setting:

• z80-asm-meter.parser.directives.defsAsInstructions: Tries to parse DEFS directive bytes as single byte instructions.

  Disabled by default.

• z80-asm-meter.parser.instructionsCacheSize: Size of the internal cache, in instructions, to lighten the metering calculations; particularly when metering large source code blocks.

  Defaults to: 200 (200 instructions).

These are the three total timing calculation available:

1. default: The default total timing calculation mode is the raw addition of the timings of the individual instructions.

2. execution flow: When the selection is a single subroutine (i.e.: there are no unconditional JP, JR or RET instructions in the selection), the execution flow total timing calculation measures the timing of the execution flow through the selection (i.e.: to the next, non selected, instruction) by considering any DJNZ or conditional JP, JR or RET instruction as not taken.

3. execution flow to the selected exit point: When the selection is a single subroutine and the selection ends at an exit point (a conditional or unconditional JP, JR or RET instruction) or calls a subroutine (a conditional or unconditional CALL), the execution flow to the selected exit point total timing calculation mode measures the timing of the execution flow to the selected exit point, by considering the last instruction as taken if it is a conditional instruction.

• z80-asm-meter.statusBar.totalTimings: Shows total timing calculations in the status bar.

  • all: Shows all the total timing calculation that apply to the selection.

    

  • combineAll: Shows all the total timing calculation that apply to the selection, but combined to reduce the size of the status bar item.

    

  • smart (default): Shows total timing calculation that are relevant to the selection.

    

  • combineSmart: Shows total timing calculation that are relevant to the selection, but combined to reduce the size of the status bar item.

    

  • best: Shows the total timing calculation that best fits the selection.

    

  • default: Does not show any alternative total timing calculation.

    

• z80-asm-meter.statusBar.totalTimingsOrder: Determines the order of the total timing calculations in the status bar when more than one total timing calculation is visible.

  • retFlowJumpCall (default): At exit point (returns) first. Execution flow next. Other exit points (jumps and calls) last. This order is the most visual, with returns ("going back") to the left, execution flow ("going down") next, and jumps and calls ("going elsewhere") to the right.

    

  • flowRetJumpCall: Execution flow first. Any exit points (returns, jumps and calls) last.

    

  • retJumpCallFlow: Any exit point (returns, jumps and calls) first, execution flow last. This order matches the timing convention of single instructions, where the conditions met (returns, jumps and calls) are to the left and the conditions not met (execution flow) are to the right.

    

• z80-asm-meter.timing.executionFlow.enabled: Enables execution flow total timing calculation.

  Enabled by default.

• z80-asm-meter.timing.executionFlow.threshold: Minimum number of instructions to be selected for the calculation of execution flow total timing.

  Defaults to: 2 (2 instructions).

• z80-asm-meter.timing.executionFlow.requireConditional: Requires at least one conditional instruction to enable execution flow total timing calculation.

  Enabled by default.

• z80-asm-meter.timing.executionFlow.icon: Execution flow total timing calculation icon in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(debug-step-over).

  

• z80-asm-meter.timing.executionFlow.stopOnUnconditionalJump: Disables execution flow total timing calculation if an unconditional JP, JR or RET instruction is found.

  Enabled by default.

• z80-asm-meter.timing.atExit.retEnabled: Enables total timing calculation of the execution flow to the selected exit point when the selection ends with a RET, RETI or RETN instruction.

  Enabled by default.

• z80-asm-meter.timing.atExit.jumpEnabled: Enables total timing calculation of the execution flow to the selected exit point when the selection ends with a DJNZ, JP or JR instruction.

  Enabled by default.

• z80-asm-meter.timing.atExit.callEnabled: Enables total timing calculation of the execution flow to the selected exit point when the selection ends with a CALL or RST instruction.

  Disabled by default.

• z80-asm-meter.timing.atExit.threshold: Minimum number of instructions to be selected for the calculation of total timing calculation of the execution flow to the selected exit point.

  Defaults to: 2 (2 instructions).

• z80-asm-meter.timing.atExit.requireConditional: Requires at least one conditional instruction to enable total timing calculation of the execution flow to the selected exit point.

  Enabled by default.

• z80-asm-meter.timing.atExit.stopOnUnconditionalJump: Disables total timing calculation of the execution flow to the selected exit point if an unconditional JP, JR or RET instruction is found.

  Enabled by default.

• z80-asm-meter.timing.atExit.retIcon: Total timing calculation of the execution flow to the selected exit point (RET, RETI or RETN instruction) icon in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(debug-step-back).

  

• z80-asm-meter.timing.atExit.jumpIcon: Total timing calculation of the execution flow to the selected exit point (DJNZ, JP or JR instruction) icon in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(debug-step-out).

  

• z80-asm-meter.timing.atExit.callIcon: Total timing calculation of the execution flow to the selected exit point (CALL or RST instruction) icon in the status bar. Any product icon, Unicode character, or plaint text can be used.

  Defaults to: $(debug-step-into).

  

• z80-asm-meter.inlayHints.enabled: Enables detection and metering of subroutines as inlay hints.

  Disabled by default.

• z80-asm-meter.inlayHints.subroutines.position: The position within the line for the inlay hints of subroutines.

  • lineStart: at the beginning of the line.

    

  • afterLabel: after the label, or at the beginning of the line if there is no label.

    

  • beforeCode: before the actual source code.

    

  • afterCode: after the actual source code.

    

  • beforeComment (default): before the trailing line comments, or at the end of the line if there are no trailing comments.

    

  • lineEnd: at the end of the line.

    

• z80-asm-meter.inlayHints.subroutines.unlabelled: Consider that unlabelled code is a subroutine.

  Disabled by default.

• z80-asm-meter.inlayHints.subroutines.nested: Consider that nested labels (lablels starting with a dot (.) or with @@) are subroutines.

  • disabled: Ignores any nested label.
  • enabled: Considers that any nested label is a new subroutine.
  • entryPoint (default): Considers that a nested label is a subroutine if it is a separate entry points.

• z80-asm-meter.inlayHints.subroutines.fallthrough: Consider that labels the code falls through are subroutines.

  Enabled by default.

• z80-asm-meter.inlayHints.exitPoint.position: The position within the line for the inlay hints of subroutine exit points.

  • lineStart: at the beginning of the line.

    

  • afterLabel: after the label, or at the beginning of the line if there is no label.

    

  • beforeCode: before the actual source code.

    

  • afterCode: after the actual source code.

    

  • beforeComment (default): before the trailing line comments, or at the end of the line if there are no trailing comments.

    

  • lineEnd: at the end of the line.

    

• z80-asm-meter.inlayHints.exitPoint.ret: Consider that conditional RET instructions are subroutine exit points.

  Enabled by default.

• z80-asm-meter.inlayHints.exitPoint.jp: Consider that conditional JP instructions are subroutine exit points.

  Enabled by default.

• z80-asm-meter.inlayHints.exitPoint.jr: Consider that conditional JR instructions are subroutine exit points.

  Disabled by default.

• z80-asm-meter.inlayHints.exitPoint.djnz: Consider that DJNZ instructions are subroutine exit points.

  Disabled by default.

• z80-asm-meter.inlayHints.exitPoint.label: When fallthrough labels are considered subroutines, controls which subroutine is considered at exit points.

  • first (default): The first label found; the first (outermost) subroutine in a chain of fallthrough subroutines.
  • closest: The last label found; the last (innermost) subroutine in a chain of fallthrough subroutines. That is, the subroutine whose label is the closest one to the exit point.

A timing hint follows the pattern: [z80=27] or [msx=32/22] with the key being:

• z80 for Z80 timings,
• msx or m1 for Z80+M1 timings,
• cpc for number of NOPs timings, or
• t or ts for the timing to be used regardless the platform. Specific platform timing hints will take precedence over t or ts generic timing hints.

The timing can be either a single value or a pair of values separated by slash (/). This is convenient for taking into account different execution paths within the called routine:

• CALL ADD_HL_A ; [msx=32/22] will be metered as 50/40 Z80+M1 clock cycles, as the result of adding 18(/18) + 32/22.

• CALL Z, ADD_HL_A ; [msx=32/22] will be metered as 50/11 Z80+M1 clock cycles, as the result of adding 18/11 + 32(/0). Please note the second timing hint (22) will be ignored in conditional operations.

In the example shown above:

• Of the timing hints of .OFF_SCREEN (41/28 clock cycles), the 41 has been added to the timing of conditional JR instruction when the condition is taken (13 clock cycles). Please note the second timing hint (28) has been ignored, as there is only one possible timing for the taken condition path.

• The timing hint of COORDS_TO_OFFSET (144 clock cycles) has been added to the timing of the CALL instruction (18 clock cycles).

Negative timings are supported. This may seem unintuitive, but serves very particular use cases including, but not limited to:

• Adjust the timing of an instruction in self-modifying code to match the timing of the replacement instruction.

• Adjust timings when part of the code is to be skipped:

      ; (...)
      jr z, .else
      pop hl  ; [msx=-100] will abort caller
  .else:
      ; (...)
      ret     ; [msx=100] remaining code in the caller
  

• z80-asm-meter.timing.hints.enabled: Enables timing hints, read from the line comment:

  • none: Disables timing hints.
  • subroutine (default): Subroutine timing hint will be added to CALL, DJNZ, JP, JR, RET or RST instructions only. If the timing hint is a pair of values, both will be added to the current source code block timings. If the instruction is conditional, the timing hint will be added to the taken branch timing only.
  • any: Any timing hint found, regardless the instruction. This includes empty (i.e.: no actual source code) lines.
  • ignoreCommentedOut: Any timing hint found, regardless the instruction. This includes empty (i.e.: no actual source code) lines, but ignores empty lines that look like commented out source code.

• z80-asm-meter.timing.hints.regexps: An array of regexp-based user-defined timing hints. The line comment will be matched agains the regular expression and the timing hint values will be read from this configuration object.

  • pattern: The pattern of the regular expression to match against the line comment.
  • flags: The string indicating the flags of the regular expression to match against the line comment. Optional.
  • z80: Declares or overrides Z80 default timing hint. Optional.
  • msx: Declares or overrides Z80+M1 timing hint (MSX standard). Optional.
  • m1: Declares or overrides Z80+M1 timing hint. Optional.
  • cpc: Declares or overrides timing hint measured in number of NOPs. Optional.
  • t: Declares or overrides default timing hint. Optional.
  • ts: Declares or overrides default timing hint. Optional.

Macro definitions can be added to either user settings (settings.json) or workspace settings (.vscode/settings.json).

As most of the macro definition fields are optional, this extension uses a best-effort to meter a macro with the provided information. But, generally speaking, there are three ways to define a macro:

1. Macro definition with instructions. Macro will be metered by aggregating the metrics of the instructions. For example:

   "z80-asm-meter.macros": [
       {
           "name": "ADD_HL_A",
           "instructions": [
               "ADD A, L",
               "LD L, A",
               "JR NC, zz",
               "INC H"
           ]
       }
   ]
   

2. Macro definition with timing and size. Macro will be metered using the provided timing and/or size. For example:

   "z80-asm-meter.macros": [
       {
           "name": "ADD_HL_A",
           "z80": "24/19", // (note that there is no cpc timing,
           "msx": "28/23", //    so this macro won't be metered
           "size": 5       //    if platform=cpc)
       }
   ]
   

3. Macro definition with both instructions and timing and/or size. Provided timing and/or size will override the metrics of the instructions. For example:

   "z80-asm-meter.macros": [
       {
           "name": "ADD_HL_A",
           "instructions": [
               "ADD A, L", "LD L, A", "JR NC, zz", "INC H"
           ],
           "msx": "23" // (overrides actual timing for platform=msx)
       }
   ]
   

• z80-asm-meter.macros: An array of user-defined macros:
  • name: The name of the macro; will be matched against the mnemonic of the source code.
  • z80: Declares or overrides Z80 default macro timing. Optional.
  • msx: Declares or overrides Z80+M1 macro timing information (MSX standard). Optional.
  • m1: Declares or overrides Z80+M1 macro timing information. Optional.
  • cpc: Declares or overrides macro timing measured in number of NOPs. Optional.
  • t: Declares or overrides default macro timing. Optional.
  • ts: Declares or overrides default macro timing. Optional.
  • size: Declares or overrides macro byte count. Optional.
  • instructions: The macro definition, as instructions. Optional.

Please find the deprecated settings, the last version where the setting was available, and the replacement setting or settings in the following table:

Early versions of this extension avoided metering more than once the same selection, and also prevented the metering to be triggered too frequently (debouncing).

From version 5.4.0 onwards, development has focused on performance improvements: now it uses a "Least Recently Used" (LRU) cache for previously metered selections, expensive RegExps have been replaced by lighter alternatives, and, since version 5.5.0, another internal LRU cache for instructions improves the performance when metering large source code blocks.

The following table compares the time took to meter 11 179 lines of source code (the fully annotated disassembly of King's Valley (© Konami 1985) by Manuel Pazos) using VS Code 1.92.1, Windows 10, AMD Ryzen 3 2200U: