1+ /*
2+ * Copyright 2026 Datadog, Inc
3+ *
4+ * Licensed under the Apache License, Version 2.0 (the "License");
5+ * you may not use this file except in compliance with the License.
6+ * You may obtain a copy of the License at
7+ *
8+ * http://www.apache.org/licenses/LICENSE-2.0
9+ *
10+ * Unless required by applicable law or agreed to in writing, software
11+ * distributed under the License is distributed on an "AS IS" BASIS,
12+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+ * See the License for the specific language governing permissions and
14+ * limitations under the License.
15+ */
116#ifndef _FRAME_H
217#define _FRAME_H
318
19+ #include < cassert>
20+ #include " vmEntry.h"
21+
422enum FrameTypeId {
523 FRAME_INTERPRETED = 0 ,
624 FRAME_JIT_COMPILED = 1 ,
@@ -10,23 +28,59 @@ enum FrameTypeId {
1028 FRAME_KERNEL = 5 ,
1129 FRAME_C1_COMPILED = 6 ,
1230 FRAME_NATIVE_REMOTE = 7 , // Native frame with remote symbolication (build-id + pc-offset)
13- FRAME_TYPE_MAX = FRAME_NATIVE_REMOTE // Maximum valid frame type
31+ FRAME_TYPE_MAX = FRAME_NATIVE_REMOTE , // Maximum valid frame type
32+ FRAME_TYPE_MASK = 0x7
1433};
1534
35+ // Packs frame type and BCI into a single int field stored in CallTrace frames.
36+ //
37+ // Bit layout of an encoded value (ENCODED_MASK set):
38+ // bit 30 RAW_POINTER_MASK — value is a raw native PC (HotSpot only)
39+ // bits 23–21 frame type — FrameTypeId (0–7)
40+ // bit 20 ENCODED_MASK — set to distinguish encoded values from raw ASGCT BCIs
41+ // bits 15–0 BCI — bytecode index (0–65534; never 65535, see BCI_MASK)
42+ //
43+ // When ENCODED_MASK is not set the field is a raw, unencoded BCI from ASGCT (non-VM stack
44+ // walking modes). Raw values may be negative: HotSpot uses -1 as a sentinel for method-entry
45+ // and synchronization-entry samples. Both encode() and bci() clamp negative values to 0 so
46+ // that 65535 (the mask value itself) is never emitted and can be treated as unreachable.
47+ // decode() returns FRAME_JIT_COMPILED for all unencoded or negative values.
1648class FrameType {
49+ // JVM spec §4.7.3 caps method bytecode at 65535 bytes, so valid BCIs are 0–65534.
50+ // The mask value 65535 (0xffff) is therefore never a valid BCI; we keep it unreachable
51+ // by clamping negative sentinels to 0 in encode() and bci().
52+ static constexpr int BCI_MASK = 0xffff ;
53+ static constexpr int TYPE_SHIFT = 21 ;
54+ static constexpr int ENCODED_MASK = 1 << 20 ; // distinguishes encoded values from raw ASGCT BCIs
55+ static constexpr int RAW_POINTER_MASK = 1 << 30 ;
1756public:
18- static inline int encode (int type, int bci) {
19- return (1 << 24 ) | (type << 25 ) | (bci & 0xffffff );
57+ // Produces an encoded int from a frame type and BCI. Negative BCIs (HotSpot -1 sentinels
58+ // for method-entry/sync-entry) are mapped to 0 rather than wrapping to 0xffff.
59+ static inline int encode (int type, int bci, bool rawPointer = false ) {
60+ assert ((!rawPointer || VM::isHotspot ()) && " Raw pointer is only valid for hotspot"
61+ assert (type >= FRAME_INTERPRETED && type <= FRAME_TYPE_MAX );
62+ int bci_bits = (bci < 0 ) ? 0 : (bci & BCI_MASK );
63+ return ENCODED_MASK | (type << TYPE_SHIFT ) | bci_bits | (rawPointer ? RAW_POINTER_MASK : 0 );
64+ }
65+
66+ // Extracts the BCI from either an encoded value or a raw ASGCT BCI.
67+ // Negative values (HotSpot -1 sentinels) are clamped to 0, matching encode().
68+ static inline int bci (int bci) {
69+ return (bci < 0 ) ? 0 : (bci & BCI_MASK );
2070 }
2171
72+ // Extracts the FrameTypeId from an encoded value.
73+ // Returns FRAME_JIT_COMPILED for unencoded raw ASGCT BCIs and for negative sentinels,
74+ // since no type information is available in those cases.
2275 static inline FrameTypeId decode (int bci) {
23- if ((bci >> 24 ) <= 0 ) {
24- // Unencoded BCI (bit 24 not set) or negative special BCI values
76+ if ((bci & ENCODED_MASK ) == 0 || bci < 0 ) {
2577 return FRAME_JIT_COMPILED ;
2678 }
27- // Clamp to valid FrameTypeId range to defend against corrupted values
28- int raw_type = bci >> 25 ;
29- return (FrameTypeId)(raw_type <= FRAME_TYPE_MAX ? raw_type : FRAME_TYPE_MAX );
79+ return (FrameTypeId)((bci >> TYPE_SHIFT ) & FRAME_TYPE_MASK );
80+ }
81+
82+ static inline bool isRawPointer (int bci) {
83+ return bci > 0 && (bci & RAW_POINTER_MASK ) != 0 ;
3084 }
3185};
3286
0 commit comments