DOCSEARCHbyAlgolia
Submit Docs

LibXenon

repository·master·Indexed 41 days ago

https://github.com/free60project/libxenon

A bare-metal homebrew library and toolchain for the Xbox 360 gaming console. It provides the environment to develop and build custom applications, including a CFE USB stack, hardware abstraction drivers, and support for compiling shaders using Tser's Shadercompiler. The project includes a build system for the toolchain and library, with optional prebuilt Docker images for a controlled development environment.

Tokens
1.9K
Snippets
4
Records
10
Agent score
51%

What's inside LibXenon

  1. Install the LibXenon toolchain, library, and auxiliary libs

    master

    Use the toolchain/build-xenon-toolchain script to install specific components of the LibXenon ecosystem. Run these commands from the repository root.

    Install the toolchain:

    ./build-xenon-toolchain toolchain

    Install the libxenon library:

    ./build-xenon-toolchain libxenon

    Install auxiliary libraries (libxenon, bin2s, zlib, libpng, bzip2, freetype, filesystems):

    ./build-xenon-toolchain libs

  2. Build LibXenon manually from source

    master

    To build LibXenon manually, you must first ensure your system meets the requirements and then use the toolchain/build-xenon-toolchain script to install different components.

    Requirements

    If you are using a Linux distribution with dnf or apt, dependencies are installed automatically. Otherwise, you must manually install:

    • flex
    • bison
    • gcc-multilib (required if on x86_64)
    • libgmp3-dev
    • libmpfr-dev
    • libmpc-dev
    • texinfo
    • git-core
    • build-essential
    • wget
    • file

    Customizing the Installation Prefix

    By default, the installation prefix is /usr/local/xenon. To use a custom location, set the PREFIX environment variable when running the build script.

    PREFIX="/home/username/xenon" ./build-xenon-toolchain toolchain

  3. Use prebuilt Docker images for LibXenon development

    master

    You can use prebuilt Docker images from the free60 Docker Hub account to avoid manual setup. This is useful for building homebrew applications in a controlled environment.

    To use the free60/libxenon image, mount your local application directory into the container and run make inside the container.

    host $ cd libxenon-homebrew-app/
host $ docker run -it -v $PWD:/app free60/libxenon:latest
docker $ cd /app
docker $ make

  4. Configure environment variables for LibXenon

    master

    After installing the toolchain, you must configure your environment to recognize the installation prefix. The primary variable is DEVKITXENON, which should point to your installation prefix (default is /usr/local/xenon).

    Manual Configuration

    You can manually export the following variables in your shell or ~/.bashrc:

    DEVKITXENON="/usr/local/xenon"
PATH="${PATH:+${PATH}:}"$DEVKITXENON"/bin:$DEVKITXENON"/usr/bin"

    Automatic Configuration via xenon-env

    Alternatively, you can run the following command to install a utility named xenon-env. Running xenon-env will automatically set the required environment variables in a new shell session:

    ./build-xenon-toolchain env-cmd

  5. Overview of LibXenon project structure

    master

    LibXenon is designed as a lightweight embedded gaming-console operating system. The project follows a specific directory structure to separate hardware abstraction, application logic, and system initialization:

    • drivers/: Contains code for single-platform and cross-platform devices and frameworks (e.g., xenon_uart, ochi, fat).
    • ports/: Contains applications, including 'hello world' binaries and various examples.
    • startup/: Contains startup code that is typically shared across different applications.

    The build system relies on complex Makefiles to selectively include or exclude components based on the specific requirements of a given port.

  6. How the CFE USB stack polling mechanism works

    master

    The CFE USB stack relies on a polling model rather than an interrupt-driven model for the host controller. To maintain the USB bus and handle device events, you must periodically call two specific polling functions:

    1. usb_poll(usbbus_t *bus): Handles interrupts originating from the USB devices themselves.
    2. usb_daemon(usbbus_t *bus): Monitors the bus for topology changes (like device insertion or removal) and manages device exploration. This routine may perform USB I/O, which in turn requires calls to usb_poll() to move data through the controller.

    Warning: Do not call usb_poll() while inside the usb_daemon() routine to avoid conflicts.

    /* Periodic calls required for the USB stack */
usb_poll(bus);
usb_daemon(bus);

  7. Implement a USB device driver in CFE

    master

    USB device drivers in CFE are implemented by providing two primary methods that must be exported to the device driver table. These methods manage the lifecycle of a device connection:

    • attach(): Called when the USB stack discovers the device. Upon attachment, the device is placed in the "addressed" state. The driver can then use usb_find_cfg_descr() to obtain endpoint and interface descriptors, and usb_set_configuration() to activate a specific configuration.
    • detach(): Called when the device is removed. When this is called, the device should be treated as already gone; do not attempt any further I/O. The driver's responsibility is to clean up resources and return.

    Note on Transfers: When a device is removed, any pending transfer requests will be canceled with a "canceled" status.

    /* Conceptual driver interface */
void attach(device_t *dev);
void detach(device_t *dev);

  8. Compile shaders using Tser's Shadercompiler

    master

    Shaders in this project must be compiled using Tser's Shadercompiler, which relies on the XNA Framework.

    Prerequisites

    To build the shader compiler itself, you need:

    • Windows
    • Visual Studio Express 2008 (C#)
    • XNA 3.0 (or older XNA releases)

    Building the Shadercompiler

    1. Download the shader compiler source: http://minilgos.perso.sfr.fr/xenkit/rshadercompiler.zip
    2. Create a new C# project in Visual Studio.
    3. Add a Reference to Microsoft.XNA.
    4. Insert the provided Program.cs into your project.
    5. Build the .exe.

    Compiling Shaders

    Once you have shadercompiler.exe, use the following command patterns to compile your .hlsl files into Xenon shader formats (.vsu, .psu, etc.):

    • Vertex Shaders: shadercompiler.exe <input_hlsl> <output_vsu> /vs
    • Pixel Shaders: shadercompiler.exe <input_hlsl> <output_psu> /ps
    # Compile a vertex shader
shadercompiler.exe vs.hlsl vs.vsu /vs

# Compile a pixel shader
shadercompiler.exe ps.hlsl ps.psu /ps

  9. Reference: CFE USB Stack Source Files

    master

    The following files constitute the CFE USB stack components:

    FileDescription
    ohci.c / ohci.hOHCI USB Host Controller Driver and register definitions.
    usbchap9.hUSB "Chapter 9" definitions (Descriptors, etc.).
    usbd.c / usbd.hUSB Basic Request and pipe management routines (device management, control pipe requests, pipe lifecycle).
    usbdebug.cDescriptor dump routines.
    usbdevs.cUSB Device Driver list (contains vendor/class ID tables for recognized devices).
    usbeth.{h,c}Driver for USB Ethernet devices (ADMtek Pegasus, CATC, Realtek).
    usbhid.cClass driver for keyboards and mice.
    usbhub.cClass driver for USB hubs and device tree management.
    usbmass.cClass driver for USB mass-storage (supports "bulk-only-no-interrupt" protocol).
    usbmain.cTop-level CFE interface and CLI command instantiation.
    usbserial.cDriver for USB serial devices (Prolific PL-2303, MCT USB-232).
    usbhack.{c,h,mk}Test harness for developing OHCI code under Linux.