~bpf.sol | 0x03: SBF Instruction Set

#Sources

The family of eBPF ISAs lacks a specification document as you may know it from other architectures. Instead, each flavor of eBPF is defined by its VM implementation. As such, Solana's SBF is currently defined by the solana_rbpf Rust crate.

All info below was compiled together from these sources:

• solana_rbpf::ebpf, which defines SBF opcodes.
  https://github.com/solana-labs/rbpf/blob/main/src/ebpf.rs
• solana_rbpf::disassembler, which implements rbpf-style disassembly.
  https://github.com/solana-labs/rbpf/blob/main/src/disassembler.rs
• The BPF target of Solana's LLVM fork, which defines the register model, bytecode encoding, and pseudocode assembly form.
  https://github.com/solana-labs/llvm-project/tree/solana-rustc/13.0-2021-09-30/llvm/lib/Target/BPF
• The Capstone BPF backend, which includes an eBPF disassembler
  https://github.com/capstone-engine/capstone/tree/next/arch/BPF

Note: This source is not authoritative. It may be outdated or conflict with actual on-chain behavior. If you find any such bugs, please consider sending corrections. And if this document helps you build software, please attribute this source – thanks!

#Assembler

Several flavors of SBF disassembly exist. Unfortunately, they are not mutually compatible.

• rbpf-style: prefix notation with C-style indirect addressing.
  Seen in rbpf-cli and tools based on the Rust implementation of Solana.
• Capstone-style: similar to rbpf-style with different ALU mnemonics.
  Seen in binary analysis tools like radare2.
• LLVM-style: infix notation resembling C pseudocode.
  Seen with LLVM tools used in the build process.

#Opcode Tables

#Legacy Load/Store class

The BPF_LD opcode family consists of special purpose opcodes inherited from Linux eBPF where they were used to access network packet input data.

ldabs* used to access instruction input data starting at 0x4_0000_0000 and ldind* was the indirect version thereof. These instructions are disabled now and have been replaced by the new load/store class.

Only lddw remains enabled on mainnet today. It moves a 64-bit immediate into a GPR. This makes it more of a 64-bit variant of mov32 than an actual load instruction. (Note that mov64 with an immediate is a synonym to mov32 – the name is misleading).

#Load/Store class

The BPF_LDX and BPF_STX classes provide common memory operations.
Memory is referenced using a base address from a GPR and an immediate offset.

Three operation groups are available:

• ldx*: Load value from memory into register (8-bit, 16-bit, 32-bit, 64-bit)
• st*: Store immediate value into memory (8-bit, 16-bit, 32-bit, 32-bit zero extended to 64-bit)
• stx*: Store value from register into memory (8-bit, 16-bit, 32-bit, 64-bit)

#64-bit ALU class

The 64-bit ALU instructions operate on general-purpose registers. The stack pointer (r10) can only be used as a source operand.

Each operation has two forms:

• rD ← OP(rD, imm)
• rD ← OP(rD, rS)

#32-bit ALU class

The 32-bit ALU instructions mostly follow their 64-bit counterparts. They operate on the lower word of the input registers. The upper half of destination registers gets implicitly zeroed.

#Endian ALU extension

The LE/BE instructions operate in 16-bit, 32-bit, or 64-bit mode, indicated by the values in the immediate field.
For example, 0xdc with destination register 1 and immediate 32 is be32 r1.
They were used for portable endianness conversions. Since Solana is always little-endian, only the BE instruction swaps bytes.

• le16 rD is equivalent to rD &= 0xFFFF.
• le32 rD is equivalent to rD &= 0xFFFF_FFFF.
• le64 rD is a nop.
• be16 rD swaps the lower 2 bytes and zeroes the upper 6.
• be32 rD reverses the order of the lower 4 bytes and zeros the upper 4.
• be64 rD reverses the order of all 8 bytes.

#Jump class

The jump instructions combine comparisons and conditional jumps. Compared to x86 or PowerPC, this simplifies the ISA by removing the condition register and using less opcodes.

The conditional jump instructions (all except ja) compare a register either against another register or an immediate value.

#Call class

The call-related opcodes push/pop the call frame stack and stack pointer.
The call frame stack is a protected data structure that can only be accessed by the call class (comparable to x86 shadow stacks).

• call saves a call frame and enters a syscall or jumps to a target indicated by the immediate.
• callx saves a call frame and jumps to the absolute address in the given register. The register index is stored in the immediate field of the instruction.
• exit restores a call frame and jumps to its return address.

Resolving call targets

The 32-bit immediate field of the call opcode contains the hash of target symbol name or syscall name. The VM resolves a call target hash using two immutable lookup maps for syscalls and jump targets, which are constructed on program load. Syscalls take precedence over jump targets. The VM aborts when a hash cannot be resolved.

The hash algorithm is Murmur3 in 32-bit mode on the UTF-8 encoding of the symbol name.

See the next post for the syscalls available in Sealevel: 0x04: Sealevel Syscalls.