Skip to content

Instantly share code, notes, and snippets.

@akitaonrails

akitaonrails/agents-xenia-canary.md

Last active January 12, 2026 00:56
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save akitaonrails/27ea45b24fba320da16b5604dc4d8eb6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save akitaonrails/27ea45b24fba320da16b5604dc4d8eb6 to your computer and use it in GitHub Desktop.
Download ZIP
AGENTS-xenia-canary.md
Raw
agents-xenia-canary.md

AGENTS.md - Xenia Canary

This document provides guidance for AI agents working in the Xenia Canary codebase - an Xbox 360 emulator.

Project Overview

Xenia Canary is an experimental fork of the Xenia Xbox 360 emulator written in C++20. The project targets:

  • Windows: Primary platform (Visual Studio 2022, D3D12/Vulkan)
  • Linux: Experimental (Clang 19+, Vulkan only)
  • Android: Experimental

Essential Commands

All commands use the xb script (or ./xenia-build.py on Linux):

# Initial setup (clones submodules, runs premake)
xb setup

# Build (default is debug)
xb build                      # Debug build
xb build --config=release     # Release build
xb build --config=checked     # Debug with AddressSanitizer

# Update and rebuild
xb pull                       # Pull changes, update submodules, run premake

# Generate project files
xb premake                    # Regenerate VS/CMake project files
xb devenv                     # Run premake and open IDE

# Code formatting (REQUIRED before commits)
xb format                     # Format staged changes
xb format --all               # Format all source files
xb lint                       # Check for lint errors
xb lint --all                 # Lint all files

# Testing
xb test                       # Run automated tests
xb gentests                   # Generate test binaries from .s files
xb gputest                    # Run GPU diff tests

# Build shaders (after modifying .xesl/.hlsl/.glsl files)
xb buildshaders               # Build all shader targets
xb buildshaders --target=spirv    # Vulkan only

# Cleanup
xb clean                      # Remove intermediate files
xb nuke                       # Remove all build/ output and reset

Build Configurations

Config Description
debug Default. Debug symbols, no optimization
release Optimized, no debug symbols (Linux), LTO (Windows)
checked Debug + AddressSanitizer for memory error detection

Platform-Specific Building

Windows:

  • Uses MSBuild: msbuild build/xenia.sln /p:Configuration=Release
  • Requires Visual Studio 2022 and Windows 11 SDK 10.0.22000.0+

Linux:

  • Uses CMake + Ninja
  • Environment: CC=clang-20 CXX=clang++-20 xb build --config=release
  • Dependencies: mesa-vulkan-drivers libc++-dev libgtk-3-dev libsdl2-dev libvulkan-dev libx11-xcb-dev ninja-build

Code Organization

xenia-canary/
├── src/xenia/              # Main source code
│   ├── app/                # Application entry, window management
│   ├── apu/                # Audio Processing Unit emulation
│   │   ├── sdl/           # SDL audio backend
│   │   ├── xaudio2/       # Windows XAudio2 backend
│   │   └── nop/           # No-op backend
│   ├── base/               # Platform utilities, threading, memory
│   ├── cpu/                # CPU emulation (PowerPC JIT)
│   │   ├── backend/x64/   # x86-64 JIT backend
│   │   ├── compiler/      # HIR compiler passes
│   │   ├── hir/           # High-level IR
│   │   └── ppc/           # PowerPC frontend
│   ├── gpu/                # GPU emulation (Xenos)
│   │   ├── d3d12/         # Direct3D 12 backend (Windows)
│   │   ├── vulkan/        # Vulkan backend
│   │   ├── null/          # No-op backend
│   │   └── shaders/       # GPU shaders (.xesl, .hlsl)
│   ├── hid/                # Human Interface Devices (controllers)
│   ├── kernel/             # Xbox 360 kernel emulation
│   │   ├── xam/           # XAM (dashboard) functions
│   │   ├── xboxkrnl/      # Kernel functions
│   │   └── xbdm/          # Debug monitor functions
│   ├── patcher/            # Game patching system
│   ├── ui/                 # UI framework, presenters
│   │   ├── d3d12/         # D3D12 UI backend
│   │   └── vulkan/        # Vulkan UI backend
│   └── vfs/                # Virtual File System
├── third_party/            # External dependencies (submodules)
├── tools/                  # Development tools
├── docs/                   # Documentation
├── android/                # Android app project
└── assets/                 # Icons and resources

Code Style and Conventions

Formatting

  • Tool: clang-format 19 with Google style base
  • Line length: 80 columns max
  • Indentation: 2 spaces (no tabs)
  • Line endings: LF (Unix-style)
  • Always run xb format before committing

Naming Conventions

Element Style Example
Files snake_case kernel_state.cc, clock.h
Classes PascalCase KernelState, Arena
Xbox kernel types X_ prefix X_KPROCESS, X_KTHREAD
Xbox object wrappers X prefix XThread, XObject
Public methods PascalCase LoadUserModule()
Getters/Setters snake_case guest_time_scalar()
Member variables trailing _ emulator_, memory_
Constants/Macros SCREAMING_SNAKE DEFINE_bool, XELOGD

File Structure

Header files (.h):

/**
 ******************************************************************************
 * Xenia : Xbox 360 Emulator Research Project                                 *
 ******************************************************************************
 * Copyright 20XX Ben Vanik. All rights reserved.                             *
 * Released under the BSD license - see LICENSE in the root for more details. *
 ******************************************************************************
 */

#ifndef XENIA_KERNEL_KERNEL_STATE_H_
#define XENIA_KERNEL_KERNEL_STATE_H_

#include <...>         // System headers
#include "xenia/..."   // Project headers

namespace xe {
namespace kernel {

class KernelState {
 public:
  // ...
 private:
  Emulator* emulator_;  // Note trailing underscore
};

}  // namespace kernel
}  // namespace xe

#endif  // XENIA_KERNEL_KERNEL_STATE_H_

Source files (.cc):

// License header (same as above)

#include "xenia/kernel/kernel_state.h"  // Own header FIRST

#include <system_headers>
#include "other/project/headers.h"

namespace xe {
namespace kernel {

// Implementation

}  // namespace kernel
}  // namespace xe

Common Patterns

CVars (Configuration Variables):

// In .cc file
DEFINE_bool(clock_no_scaling, false, "Disable guest clock scaling", "CPU");
DECLARE_bool(clock_source_raw);  // Declare from another file

Logging:

XELOGD("Debug message: {}", value);    // Debug
XELOGI("Info message");                 // Info
XELOGW("Warning message");              // Warning
XELOGE("Error message");                // Error

Assertions:

assert_true(condition);
assert_false(condition);
assert_not_null(pointer);
xenia_assert(condition);

Xbox Structure Definitions:

struct X_KPROCESS {
  xe::be<uint32_t> field;  // Big-endian field
  // ...
};
static_assert_size(X_KPROCESS, 0x60);  // Verify struct size

Smart Pointers:

object_ref<XThread> thread;  // Reference-counted Xbox object

Comments and TODOs

  • Properly punctuate comments (capitalization, periods)
  • Format TODOs: // TODO(yourgithubname): Description.
  • Reference games by title ID (hex), not name

Testing

Unit Tests

  • Located in src/xenia/*/testing/
  • Run with: xb test
  • Test targets: xenia-base-tests, xenia-cpu-ppc-tests

PPC Instruction Tests

  • Assembly files in src/xenia/cpu/ppc/testing/
  • Named instr_*.s or seq_*.s
  • Generate binaries: xb gentests

GPU Tests

  • Trace-based GPU diff testing
  • Run with: xb gputest

Important Gotchas

Build System

  • Always run xb premake after adding/removing source files
  • Premake automatically picks up files via recursive_platform_files()
  • Platform-specific files use suffixes: _win.cc, _posix.cc, _android.cc

Code Contributions

  • Never reference XDK - all info must be from legal reverse engineering
  • No game-specific hacks - workarounds must be in terms of common interfaces
  • Reference games by title ID (e.g., 0x12345678), never by trademarked names
  • Keep git history clean - squash/rebase as needed

Memory and Endianness

  • Xbox 360 is big-endian; use xe::be<T> for guest memory structures
  • Guest memory starts at address 0x00000000 in emulator space
  • JIT code lives around 0xA0000000

Debugging Tips

  • VS: Set working directory to $(SolutionDir)..\..
  • Pass --log_file=stdout to log to console
  • Pass --emit_source_annotations for better JIT disassembly
  • Use --flagfile=flags.txt for persistent options

Architecture Notes

CPU Emulation

  • PowerPC to x86-64 JIT compilation
  • HIR (High-level IR) as intermediate representation
  • Multiple compiler passes for optimization

GPU Emulation

  • Xenos GPU (ATI R500-based)
  • Shader translation: Xbox shader bytecode → DXBC/SPIR-V
  • Render target cache for tile-based rendering emulation

Kernel Emulation

  • Emulates Xbox 360 kernel APIs
  • Thread scheduling, memory management, file system
  • XAM for dashboard/system UI functions

CI/CD

The project uses GitHub Actions:

  • Lint check: Runs xb lint --all on all PRs
  • Linux build: Clang 20, Release config
  • Windows build: VS 2022, Release config
  • Artifacts uploaded for successful builds

Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment