Skip to content

[SIMD-0321]: VM Register 2 Instruction Data Pointer #321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[SIMD-0321]: VM Register 2 Instruction Data Pointer #321

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a6a212a
vm register 2 instruction data pointer
buffalojoec Jul 8, 2025
7b10614
deanmlittle feedback
buffalojoec Jul 12, 2025
18bfb35
lucasste feedback
buffalojoec Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions proposals/0321-vm-r2-instruction-data-pointer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
simd: '0321'
title: VM Register 2 Instruction Data Pointer
authors:
- Joe Caulfield (Anza)
category: Standard
type: Core
status: Review
created: 2025-07-11
feature: (fill in with feature key and github tracking issues once accepted)
---

## Summary

Provide a pointer to instruction data in VM register 2 (`r2`) at program
entrypoint, enabling direct access to instruction data without having to parse
the accounts section of the serialized input region.

## Motivation

Currently, sBPF programs must parse the accounts section of the serialized
input region to locate instruction data. The serialization layout places
accounts before instruction data, requiring programs to iterate through all
accounts before
reaching the instruction data section. This is inefficient for programs that
primarily or exclusively need to access instruction data.

By providing a direct pointer to instruction data in `r2`, programs can
immediately access this data without any parsing overhead, resulting in
improved performance and reduced compute unit consumption.

## New Terminology

* **Instruction data pointer**: A 64-bit pointer (8 bytes) stored in VM
register 2 that points directly to the start of the instruction data
section in the input region.

## Detailed Design

When the feature is activated, the VM shall set register 2 (`r2`) to contain a
pointer to the beginning of the instruction data section within the input
region. The instruction data format remains unchanged:
Comment on lines +40 to +42
Copy link

@topointon-jump topointon-jump Jul 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How long must the pointer retain this value for? The whole execution, or only for a certain period of time/number of instructions? What is considered "at program entrypoint" - just the first instruction? Do you mind clarifying in the SIMD? Thank-you!

Apologies if I missed this anywhere.

Copy link
Contributor

@Lichtso Lichtso Jul 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only the first instruction, r2 is the second argument register, thus a parameter of the entrypoint function.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will add this to the proposal!


```
[8 bytes: data length (little-endian)][N bytes: instruction data]
```

This pointer in `r2` is made available to all programs, under all loaders,
regardless of whether or not the value is read. Prior to this feature, `r2`
contains uninitialized data at program entrypoint.

Despite technically being a breaking change, mainnet-beta testing with a modified
Agave validator confirms no divergence in execution or consensus. This is
because `r2` can typically only be accessed uninitialized through contrived
examples such as assembly manipulation or compiler bugs. The performance
benefits are considered a reasonable tradeoff. See security section for more
details.

**Register Assignment:**

* `r1`: Input region pointer (existing behavior)
* `r2`: Pointer to instruction data section (new)

**Pointer Details:**

* The pointer in `r2` points to the first byte of the actual instruction data,
NOT the length field.
Comment on lines +66 to +67
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not point it to the length?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, it should be pointing to the length field and that could then be offset to get the actual data pointer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a bad idea that complicates everything downstream from it. The major benefit of the r2 upgrade is the ability to statically derive instruction data from fixed offsets. Length is typically only accessed once and can be derived from an offset of -8. Conversely, having to add 8 all of your static offsets or burn an additional register/cu to store another pointer makes no sense.

Copy link
Contributor Author

@buffalojoec buffalojoec Jul 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, originally I had length as well, but a few people in the discussion requested we point to the data. There are also areas where we subtract 8 to obtain a length in the SDK/tooling already, so this pattern isn't too unusual.

https://github.com/anza-xyz/solana-sdk/blob/df57ce256ba2b427c9e480d7e5e5993a2b7414bf/account-info/src/lib.rs#L170

Ultimately, it makes no difference to me. I think it should be whatever the people who will use it think is best.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Conversely, having to add 8 all of your static offsets or burn an additional register/cu to store another pointer makes no sense.

I mentioned this on the discussion @buffalojoec pointed. I'm not confident the gains will be noticeable. r2 stores function call arguments, so you'll lose the reference to the pointer as soon as you call a function. In that case, it won't make a difference if you have r2 pointing directly to the data or you've already offset it and stored it elsewhere. Either you'll have a spill or you'll use another register.

If you design an entry point without any function call, you may see a difference. But again, if this entry point has enough operations, you'll need to spill the value to the stack.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my proof-of-concept I demonstrated how a program can simply define its entrypoint to receive the r2 parameter, which would turn it into a stack variable, no?

#[no_mangle]
pub unsafe extern "C" fn entrypoint(
    input: *mut u8,
    instruction_data_offset: u64,
) -> u64 {
    let _ = instruction_data_offset;
    /* ... */
}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not necessarily. It will only be stored in the stack when needed. In a very simple function that needs no stack space, it will stay in a register. These cases aren't so common, though.

I saw your example mentions instruction_data_offset. It is supposed to be the pointer, right? not the offset from the starting pointer.

* The pointer value in `r2` is stored as a native 64-bit pointer (8 bytes) in
little-endian format (x86_64).
* When there is no instruction data (length = 0), `r2` still points to the
offset immediately proceeding the instruction length counter; in this case,
the first byte of the program ID, ensuring it will always point to valid,
readable memory within the bounds of the input region.
* The pointer must always point to valid memory within the input region bounds.

## Alternatives Considered

1. **Provide a pointer to instruction data length**: Store a pointer to the
instruction data length field in `r2`. However, providing a direct pointer to
the start of instruction data is more ergonomic.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

providing a direct pointer to the start of instruction data is more ergonomic.

Why is that? If I were to deserialize, I would expect to see the length first.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider reading up on how our existing Rust SDKs work: https://github.com/anza-xyz/solana-sdk/blob/master/account-info/src/lib.rs#L170

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the point for discussion is whether it is wrong or right to subtract the pointer. The account info point you just mentioned needs the length first: https://github.com/anza-xyz/solana-sdk/blob/d708b8a829743013accc5f537709b5dd7b7fbc91/program-entrypoint/src/lib.rs#L429-L438.

Since in most cases, you'll need to validate the data pointer to ensure you are not reading garbage or doing an out of bounds read, you'll fetch the length first.

I believe the design should incentivize the correct management of pointers and memory regions, so my suggestion to keep pointing to the length first is based on that.


2. **Provide optional entrypoint parameter**: Allow programs to opt-in via a
different entrypoint signature. The current approach is simpler as it avoids
supporting multiple entrypoint signatures and makes the pointer universally
available. This relies on the assumption that no programs depend on the
garbage value previously in `r2`.

3. **Modify serialization layout**: The serialization layout will eventually be
overhauled with ABI v2, a comprehensive upgrade that could resolve this issue
among many others. Given the significant scope of ABI v2 and potential for
delays, this targeted optimization provides immediate value and remains
compatible with ABI v2.

## Impact

On-chain programs are positively impacted by this change. The new `r2` pointer
gives programs the ability to efficiently read instruction data, further
customize their program's control flow and maximize compute unit effiency.
However, any programs that currently depend on the uninitialized/garbage value
in `r2` at entrypoint will break when this feature is activated.

Core contributors must implement this feature, which should be extremely
minimally invasive, depending on the VM implementation.

## Security Considerations

Programs should read and validate the instruction data length (stored at `r2 - 8`)
before accessing data via the `r2` pointer. Failing to check the length could
result in reading unintended memory contents or out-of-bounds access attempts.
Comment on lines +107 to +109
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exactly because of this, I would expect to read the length first. So pointing to the length would be more straightforward.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point! I can go either way. My original PoC was pointing to length, until a few devs requested the actual data.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I vote for a pointer to the length.


Additionally, programs that currently rely on `r2` containing uninitialized or
garbage data at entrypoint will experience breaking changes when this feature
is activated. While it is technically possible with assembly manipulations, no
compiled code uses `r2` with an uninitialized value except in the case of
`sol_log_64_` which is not a direct security concern as logs are not enshrined
by consensus.

## Backwards Compatibility

This feature is only backwards compatible for programs that currently do not
read from `r2` at program entrypoint.

This feature is NOT backwards compatible for any programs that depend on the
uninitialized/garbage data previously in `r2`.
Comment on lines +123 to +124
Copy link

@topointon-jump topointon-jump Jul 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because of this, this change should be feature-gated to reduce the risk of a divergence. It's possible that, for a given client implementation, the uninitialized data is the same across all the nodes. If a program is taking advantage of this (accidental or otherwise) and we change this value, then we could see a divergence.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is only uninitialized data from the PoV of the program, the runtime should always have set it to zero so far. Yes, the change needs a feature gate, but we have tested that it would work for all currently used programs on MNB.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did plan to feature-gate this change. I thought all SIMDs were feature gates. If I need to call that out explicitly in the proposal, I can.

Loading