Crate faucon_asm[−][src]

Expand description

Rust library for processing NVIDIA Falcon assembly.

About the Falcon

The Fast Logic Controller is a series of general-purpose embedded microprocessors that have been produced since around 2005. With over three billion units shipped, the Falcon has been used in many different places and platforms, primarily NVIDIA GPUs starting from G98, but really everywhere a controller for logic processing was needed.

Falcon units consist of:

the core processor with its SRAM for code and data
the I/O space for communication with host systems
FIFO interface logic (optional)
memory interface logic (optional)
cryptographic AES coprocessor, making the Falcon a “secretful unit” (optional)
unit-specific logic to control, depending on how the processor is used (optional)

The Instruction Set Architecture

The heart of this crate is the Instruction structure. Objects of it shall never be created manually, unless you know what you are doing. Rather, instances may be obtained through the read_instruction function, which disassembles a chunk of binary data into Falcon assembly.

See the respective documentation for more details on the usage possibilities.

Pretty-printing instructions

Instructions implement the std::fmt::Display trait so they can emit valid assembly code for the wrapped instruction which could be thrown at an assembler.

let instruction = unsafe {
    faucon_asm::read_instruction(&mut &[0xBF, 0x1F][..], &mut 0).unwrap()
};

assert_eq!(instruction.to_string(), "ld.w $r15 D[$r1]");

Instruction operands

Of course, an Instruction object lets you access its operands which are used to execute the operation. The various different types of operands are portrayed by the Operand enumeration. A list of instruction operands can be obtained through Instruction::operands.

Disassembling instructions

As mentioned previously, the read_instruction function should be used to disassemble raw instruction bytes into Instruction objects. The function can be called repeatedly on a buffer of code until an error or FalconError::Eof occurs.

However if a user wishes to pretty-print a sequence of instructions to a special output sink, the Disassembler structure may be used which provides additional formatting capabilities which include the current program counter of an instruction and its representation in raw bytes.