Gait

Gait is a High Level Assembler (HLASM) interpreter for Visual Studio Code. It lets you write, run, step through and debug z/Architecture assembler inside VS Code, with no mainframe connection. Gait was previously called Forge.

The reference for every supported instruction, including where Gait differs from real hardware, is in supported_instructions.md.

Features

• Run, step and step back through assembler, with breakpoints
• Registers, PSW and condition code that you can edit before and during a run
• A memory viewer (hex and character) and a fields view of DS, DC and DSECT storage, both editable
• A machine code view showing what each instruction assembles to, at its address
• CSECTs, DSECTs, USING and DROP, literals, and multiple CSECTs with branches between them
• Fixed-point, compare, logical, shift and packed decimal instructions, and branching including extended mnemonics
• Linkage with save areas, and the linkage stack with BAKR and PR
• Character data held as EBCDIC, and real byte addresses
• Program output from WTO in its own tab
• A built-in form for reporting bugs and requesting features
• An instruction reference that documents how each instruction differs from real hardware

Requirements

Visual Studio Code 1.96 or later. Nothing else needs to be installed.

Installing

Gait installs from a .vsix file. In VS Code, open the Extensions view, choose Install from VSIX... from the ... menu, and pick the file. A Visual Studio Marketplace listing is planned.

Extension Usage

1. Open an assembly file and highlight the code you want to run, then right-click and choose Load Assembly Code. With nothing highlighted, the whole file is loaded.

   Gait processes the CSECTs, DSECTs, USING statements and storage that come before your selection, so addresses and base registers are set up the way your code expects. Execution starts at the first instruction in your selection.

2. The Gait panel opens with your code, and an arrow marks the next instruction. The Code tab shows the source, Object shows the machine code, and WTO shows program output. Registers, the PSW and the condition code are shown alongside, and memory can be viewed as Fields, Equates or JSON.

3. To change a register or a memory value before running, edit it in the panel.

4. Run the code with the buttons in the panel:

   • Run executes from the start of your selection until it reaches the end of the selection, returns, or hits a breakpoint. A branch to code outside the selection still runs.
   • Step executes one instruction.
   • Step Back undoes the last instruction.
   • Stop halts a running program.
   • Clear resets the machine.

Registers, the PSW, the next-instruction arrow and memory update as the code runs. Anything the program writes with WTO appears in the WTO tab.

Running in the development environment

Run:

npm install

This installs the dependencies for the extension and the ui/ sub-project. Run npm run build to build both the UI and the extension. To run the extension, press F5 to open the VS Code development host, which opens the demo folder of sample programs.

To have UI changes recompile automatically, run npm run watch-ui from the project's root directory in a command line, then press F5. UI changes recompile and should update in the development host on their own.

See CONTRIBUTING.md for more.

Known Issues

Register display breaks on very thin windows, a fix for this is being worked on.

License

Copyright 2025 21CS

Licensed under the Apache License, Version 2.0. The full text is also included in the LICENSE file.

Release Notes

0.1.1

Initial Hackathon Release

0.1.2

Second Hackathon Release

1.1.0

4/16 Initial Test Build!

1.1.1 - 7/14/26 - Build 2! With a lot of small bug fixes and smaller file size.

New Features:

• UI Overhaul
• Resizing of each of the panel elements using a draggable divider
• Proper scaling at all sizes, as well as a lot of size handling functions
• Dynamic resizing of memory and register views, which both allow more horizontal elements at wider screen sizes
• WTO notification dot
• Memory, registers, and field values now all accept inputs and update immediately in memory
• Toggle buttons and functionality for char, decimal, and binary views for memory, registers and field views
• Code view now scrolls to PSW location on jump or instruction execution
• Added accent color switching button with default colors that match the ISPF colors
• Added tutorial button, which gives an explanation of each function in the UI
• Added breakpoints
• Memory change highlighting

1.1.2 - 7/29/26 - Build 3! Many new features

New Features:

• EBCDIC Translation: Machine now internally uses EBCDIC instead of ASCII, translating it before prints to handle X86 text
• Added new instructions, CLC, CLR, BASR, BAL, BC, BCR, BCTR
• Added Shift instructions SLL, SRL, SLA, and SRA
• Added Packed Decimal instructions ZAP, AP, SP, CP, MP, DP, PACK, UNPK
• Registers are now basic integers and can be defined by equates
• Equates now has its own tab to see equated fields
• Memory view now has spaces between Fullwords
• DSECTS now work in any location, not just the bottom of the file
• Changing values in memory now accurately reflects field highlighting and vice-versa
• Condition Code register is now visible in the UI
• Step backward button now implemented using a snapshot of the machine for each instruction executed
• Syntax highlighting of assembly in code view
• Many small bugfixes

1.1.3 - 8/12/26 - Build 4: Memory Build out, Machine Code, and More!

General:

• Improved error messaging
• Entire module loading now accounted for. Ctrl + a (to highlight all) and loading code now works properly
• Added screen to submit bug reports and feature requests, updated tutorial to show recent changes
• DSECT names now persist at top of field panel to show which DSECT fields user is looking at
• Modules without an explicitely defined CSECT or DSECT now work
• All demos now run completely
• New demos
• Stop Button is now red

Saving/Restoring Registers:

• Default savearea now provided in R13 on program load
• Save/restore caller registers routine now supported
• Linkage stack added as an alternative to savearea
• BAKR and PR instructions added and work with linkage stack

Memory Changes:

• Storage macro now returns address of storage area in R1
• Save area for saving caller register is visible in the memory view as *SAVE AREA*
• Memory panel now scrolls to changed locations, and will switch to the DSECT being updated

CSECT / Code View Changes:

• Code view now shows entire module, graying out areas not highlighted by user or part of a CSECT
• Multiple CSECT support, and dropdown selector for CSECTS
• Branching between CSECTS for subroutines using BASR now supported
• Branch/jump instructions can now leave the boundary of the highlighted area. Only leaving the area without a branch or exiting to entry address will cause program end now.
• Implemented fuzzy search for code panel

Machine / Object Code Changes:

• Machine code is now generated using mnemonics from each instructions object, and the provided operands
• Machine code exists in a real place in memory, visible in 'object' tab in the code panel
• View for object code shows address, machine code in hex, and associated assembly code
• Queued instruction is also highlighted in object view

Instruction Changes:

• Added all extended branching instructions: BM, BNM, BO, BNO, BNP, BNZ, BE, BNE, BH, BL, BNH, BNL, BZ, BP, and BM
• Added STM and LM for caller registers routine
• XC, ST, and BR now use register offsets and work properly
• YREGS macro support added
• WTO now supports character literals

Bug fixes:

• Bug causing code to load incorrectly on first launch fixed
• Fix for frontend delay - UI updates now have a buffer, and will skip updates if necessary during run to keep up with backend execution
• Register displacement and displacement multiples now supported for all instructions with D(B) in their format
• If code contains records over 72 or 80 characters, a divider line will show up at those columns for the whole module
• Fixes for header instructions (title ,equ, and DCBD directives) causing parsing error
• Queued instruction no longer shows inline comments
• DSECTS with no fields (such as the save area) no longer show as an empty section in the Fields view
• Equates view now shows all equates, not just register EQUs

1.2.0 - 11/5/26 - Renamed to Gait and released as open source

General:

• Forge is now Gait. The extension ID is now 21CS.gait, so uninstall the old Forge extension before installing this one
• New Gait logo and icon
• Released under the Apache License 2.0
• The description box on the bug report screen now starts at 4 lines tall instead of filling the panel
• Supported instructions reference trimmed and checked against the current instruction set
• The view in the panel is now titled "Gait"

Bug fixes:

• Fixed the panel sometimes going blank after sitting unused. It now stays loaded while hidden, and shows a message if its page can't be loaded
• The welcome screen no longer describes the software as proprietary