struct_ops: add code comments

Signed-off-by: shun159 <[email protected]>

Author: shun159

collection.go

@@ -757,9 +757,8 @@ func (cl *collectionLoader) populateDeferredMaps() error {
 	return nil
 }
 
-// copyDataMember processes an individual member of the user-defined struct.
-// It determines whether the member is a function pointer or data member,
-// and handles it accordingly by setting up program attachments or copying data.
+// copyDataMember copies one field from the user struct into the kernel buffer.
+// If the field is a function pointer, record attach metadata instead.
 func (cl *collectionLoader) copyDataMember(
 	idx int,
 	member btf.Member,
@@ -779,8 +778,8 @@ func (cl *collectionLoader) copyDataMember(
 
 	kernMember, err := getStructMemberByName(kern.typ, memberName)
 	if err != nil {
+		// allow missing kernel member if user data is zero
 		if isMemoryZero(memberData[:memberSize]) {
-			// Skip if member doesn't exist in kernel BTF and data is zero
 			return nil
 		}
 		return fmt.Errorf("member %s not found in kernel BTF and data is not zero", memberName)
@@ -793,6 +792,8 @@ func (cl *collectionLoader) copyDataMember(
 
 	kernMemberOff := kernMember.Offset / 8
 	kernMemberData := structOps.kernVData[kernMemberOff:]
+
+	// normalize user/kernel types (strip typedef/qualifiers, one level)
 	memberType, err := skipModsAndTypedefs(kern.spec, member.Type)
 	if err != nil {
 		return fmt.Errorf("user: failed to skip typedefs for %s: %w", memberName, err)
@@ -803,6 +804,7 @@ func (cl *collectionLoader) copyDataMember(
 		return fmt.Errorf("kern: failed to skip typedefs for %s: %w", kernMember.Name, err)
 	}
 
+	// function-pointer member: map to program & record attach info
 	if _, ok := memberType.(*btf.Pointer); ok {
 		var fnName string
 
@@ -831,11 +833,13 @@ func (cl *collectionLoader) copyDataMember(
 			return fmt.Errorf("program %s: unexpected attach type %d", ps.Name, attachType)
 		}
 
+		// where the kernel expects the prog FD to be written
 		kernFuncOff := kern.dataMember.Offset/8 + kern.typ.Members[kernMemberIdx].Offset/8
 		structOps.kernFuncOff[idx] = int(kernFuncOff)
 		structOps.progAttachType[ps.Name] = attachType
 		cl.stOpsProgsToMap[ps.Name] = ms.Name
 
+		// seed program with attach metadata (checked at load time)
 		ps.Instructions[0].Metadata.Set(structOpsProgMetaKey{}, &structOpsProgMeta{
 			attachBtfId: kern.typeID,
 			attachType:  attachType,
@@ -854,8 +858,8 @@ func (cl *collectionLoader) copyDataMember(
 	return nil
 }
 
-// initKernStructOps collects typed metadata for struct_ops maps from the CollectionSpec.
-// It does not modify specs nor create kernel objects. Value population happens in a follow-up PR.
+// initKernStructOps indexes struct_ops maps: resolve kernel types, allocate per-map state,
+// and stage copy/attach metadata. No kernel objects are created here.
 func (cl *collectionLoader) initKernStructOps() error {
 	for _, ms := range cl.coll.Maps {
 		if ms.Type != StructOpsMap {
@@ -872,12 +876,14 @@ func (cl *collectionLoader) initKernStructOps() error {
 			return fmt.Errorf("user struct type should be a Struct")
 		}
 
+		// resolve kernel-side types (target + wrapper)
 		kernTypes, err := findStructOpsKernTypes(userStructType)
 		if err != nil {
 			return fmt.Errorf("find kern_type: %w", err)
 		}
 		ms.Value = kernTypes.typ
 
+		// allocate per-map state (names, offsets, kernel buffer, attach types, typeID)
 		structOps := &structOpsSpec{
 			make([]string, len(kernTypes.typ.Members)),
 			make([]int, len(kernTypes.typ.Members)),
@@ -893,7 +899,7 @@ func (cl *collectionLoader) initKernStructOps() error {
 			return err
 		}
 
-		// copy data from user-defined struct to kern_vdata
+		// populate kernel buffer & record attach info per member
 		for idx, member := range kernTypes.typ.Members {
 			if err := cl.copyDataMember(
 				idx, member,

map.go

@@ -574,6 +574,8 @@ func (spec *MapSpec) createMap(inner *sys.FD) (_ *Map, err error) {
 				return nil, fmt.Errorf("value must be Struct type")
 			}
 
+			// struct_ops: resolve wrapper type ("bpf_struct_ops_<name>") and
+			// record kernel-specific BTF IDs / FDs needed for map creation.
 			userStructType, s, modBtfObjId, err := findStructByNameWithPrefix(s, userStType)
 			if err != nil {
 				return nil, fmt.Errorf("lookup struct type: %w", err)
@@ -589,11 +591,14 @@ func (spec *MapSpec) createMap(inner *sys.FD) (_ *Map, err error) {
 			attr.BtfFd = uint32(h.FD())
 
 			if modBtfObjId != 0 {
+				// BPF_F_VTYPE_BTF_OBJ_FD is required if the type comes from a module
 				attr.MapFlags |= sys.BPF_F_VTYPE_BTF_OBJ_FD
+				// resolve a module handler for the kernel model
 				modH, err := btf.NewHandleFromID(btf.ID(modBtfObjId))
 				if err != nil {
 					return nil, fmt.Errorf("open module BTF (id=%d): %w", modBtfObjId, err)
 				}
+				// set FD for the kernel module
 				attr.ValueTypeBtfObjFd = int32(modH.FD())
 				defer modH.Close()
 			}

prog.go

@@ -397,6 +397,7 @@ func newProgramWithOptions(spec *ProgramSpec, opts ProgramOptions, c *btf.Cache)
 
 	if spec.Type == StructOps {
 		if meta, ok := spec.Instructions[0].Metadata.Get(structOpsProgMetaKey{}).(*structOpsProgMeta); ok {
+			// set AttachBtfId / ExpectedAttachType from metadata
 			attr.AttachBtfId = sys.TypeID(meta.attachBtfId)
 			attr.ExpectedAttachType = meta.attachType
 
@@ -407,6 +408,7 @@ func newProgramWithOptions(spec *ProgramSpec, opts ProgramOptions, c *btf.Cache)
 					return nil, fmt.Errorf("open module BTF handle (id=%d): %w", meta.modBtfObjID, err)
 				}
 				modH = h
+				// set AttachBtfObjFd if the type comes from a module
 				attr.AttachBtfObjFd = uint32(h.FD())
 				defer modH.Close()
 			}

struct_ops.go

@@ -18,39 +18,57 @@ type structOpsProgMeta struct {
 	modBtfObjID uint32
 }
 
-// structOpsKernTypes holds information about kernel types related to struct_ops
+// structOpsKernTypes groups all kernel-side BTF artefacts that belong to a
+// resolved struct_ops.
 type structOpsKernTypes struct {
 	spec *btf.Spec
-	// The target kernel struct type
-	typ *btf.Struct
-	// The BTF type ID of the target kernel struct
+	// target kernel struct type (e.g. tcp_congestion_ops).
+	typ    *btf.Struct
 	typeID btf.TypeID
-	// The wrapper struct type that contains the target struct
+	// wrapper struct "bpf_struct_ops_<name>" that contains typ.
 	valueType *btf.Struct
-	// The member within ValueType that holds the target struct
+	// The *btf.Member within valueType that embeds typ.
 	dataMember *btf.Member
-	// mod_btf
+	// The BTF object ID of the module where the type was found
+	// 0 if resolved in vmlinux.
 	modBtfObjId uint32
 }
 
 // used to holds "environment specific" data
 type structOpsSpec struct {
-	// attachType -> programSpec
+	// programName keeps track of program symbols by attach order.
 	programName []string
+
+	// kernFuncOff contains the byte offsets into kernVData where
+	// program FDs must be written for function pointer members.
 	kernFuncOff []int
-	/* e.g. struct bpf_struct_ops_tcp_congestion_ops in
-	 *      btf_vmlinux's format.
-	 * struct bpf_struct_ops_tcp_congestion_ops {
-	 *	[... some other kernel fields ...]
-	 *	struct tcp_congestion_ops data;
-	 * }
-	 * kern_vdata-size == sizeof(struct bpf_struct_ops_tcp_congestion_ops)
-	 * bpf_map__init_kern_struct_ops() will populate the "kern_vdata"
-	 * from "data".
+
+	/*
+	 * kernVData mirrors the kernel-side representation of the
+	 * struct_ops type, including its nested data. For example:
+	 *
+	 *   struct bpf_struct_ops_tcp_congestion_ops {
+	 *       [... kernel internal fields ...]
+	 *       struct tcp_congestion_ops data;
+	 *   }
+	 *
+	 * In this case, len(kernVData) == sizeof(struct bpf_struct_ops_tcp_congestion_ops).
+	 * copyDataMember() will copy user-supplied data
+	 * into kernVData, which is then pushed into the map.
 	 */
-	kernVData       []byte
-	kernTypes       *structOpsKernTypes
-	progAttachType  map[string]sys.AttachType
+	kernVData []byte
+
+	// kernTypes describes the BTF types of the target struct_ops
+	// object and its nested members, used for resolving offsets
+	// and function pointer
+	kernTypes *structOpsKernTypes
+
+	// progAttachType maps program names to the sys.AttachType
+	// expected by the kernel when attaching each function pointer.
+	progAttachType map[string]sys.AttachType
+
+	// progAttachBtfID holds the BTF type ID of the struct_ops
+	// target in vmlinux
 	progAttachBtfID btf.TypeID
 }
 
@@ -69,11 +87,8 @@ type structOpsMeta struct {
 	data []byte
 }
 
-// extractStructOpsMeta returns the *structops.Meta embedded in a MapSpec’s Contents
-// according to the struct-ops convention:
-//
-//	contents[0].Key   == uint32(0)
-//	contents[0].Value == *structopsMeta
+// extractStructOpsMeta retrieves the structOpsMeta value embedded in a
+// MapSpec's Contents, following the struct_ops map convention.
 func extractStructOpsMeta(contents []MapKV) (*structOpsMeta, error) {
 	if len(contents) == 0 {
 		return nil, fmt.Errorf("struct_ops: missing meta at Contents[0]")
@@ -92,11 +107,15 @@ func extractStructOpsMeta(contents []MapKV) (*structOpsMeta, error) {
 	return &meta, nil
 }
 
-// findByTypeFromStruct searches the given BTF struct `st` for the *first* member
-// whose BTF type **sidentity** equals `typ` (after resolving modifiers).
+// findByTypeFromStruct searches for the first member of a struct whose
+// resolved BTF type ID matches the given typ.
 //
-// The comparison is done via TypeID equality inside the same Spec, so a
-// typedef chain that ultimately refers to the same concrete type will match.
+// It resolves the BTF type ID of typ and compares it against each
+// member’s TypeID in st.Members. If a match is found, the corresponding
+// *btf.Member is returned.
+//
+// Returns an error if typ cannot be resolved, if any member type
+// resolution fails, or if no member with the requested type exists.
 func findByTypeFromStruct(spec *btf.Spec, st *btf.Struct, typ btf.Type) (*btf.Member, error) {
 	typeId, err := spec.TypeID(typ)
 	if err != nil {
@@ -116,20 +135,45 @@ func findByTypeFromStruct(spec *btf.Spec, st *btf.Struct, typ btf.Type) (*btf.Me
 	return nil, fmt.Errorf("member of type %s not found in %s", typ.TypeName(), st.Name)
 }
 
-// findStructByNameWithPrefix looks up a BTF struct whose name is the given `name`
-// prefixed by `structOpsValuePrefix` (“bpf_dummy_ops” → “bpf_struct_ops_bpf_dummy_ops”).
+// findStructByNameWithPrefix resolves a struct_ops "value" type by name,
+// after applying the standard prefix convention.
+//
+// It expects val to be the user-visible struct type (e.g. "bpf_dummy_ops")
+// and looks up the kernel-side wrapper name:
+//
+//	"bpf_dummy_ops" -> "bpf_struct_ops_bpf_dummy_ops"
+//
+// Returns the matching *btf.Struct, the *btf.Spec it was found in (either the
+// base vmlinux spec or a module spec), and the module BTF ID (0 for vmlinux).
+// See doFindStructTypeByName for resolution details and error behavior.
 func findStructByNameWithPrefix(s *btf.Spec, val *btf.Struct) (*btf.Struct, *btf.Spec, uint32, error) {
 	return doFindStructTypeByName(s, structOpsValuePrefix+val.TypeName())
 }
 
-// findStructTypeByName iterates over *all* BTF types contained in the given Spec and
-// returns the first *btf.Struct whose TypeName() exactly matches `name`.
+// findStructTypeByName resolves the exact BTF struct type that corresponds
+// to typ.TypeName() by searching first in vmlinux and then across all loaded
+// kernel modules.
+//
+// Returns the first *btf.Struct that matches the name verbatim, the *btf.Spec
+// where it was found, and the module BTF ID (0 if found in vmlinux).
+// If no matching struct exists anywhere, btf.ErrNotFound is returned.
 func findStructTypeByName(s *btf.Spec, typ *btf.Struct) (*btf.Struct, *btf.Spec, uint32, error) {
 	return doFindStructTypeByName(s, typ.TypeName())
 }
 
-// doFindStructTypeByName iterates over *all* BTF types contained in the given Spec and
-// returns the first *btf.Struct whose TypeName() exactly matches `name`.
+// doFindStructTypeByName looks up a struct type with the exact name in the
+// provided base BTF spec, and falls back to scanning all loaded module BTFs
+// if it is not present in vmlinux.
+//
+// Search order and behavior:
+//  1. vmlinux (base spec): try AnyTypeByName(name). If it exists and is a
+//     *btf.Struct, return it immediately with moduleID=0.
+//     - If AnyTypeByName returns a non-notfound error, the error is propagated.
+//     - If a type is found but is not a *btf.Struct, we fall back to modules.
+//  2. modules: see findStructTypeByNameFromModule.
+//
+// Returns (*btf.Struct, *btf.Spec, moduleID, nil) on success, or btf.ErrNotFound
+// if no matching struct is present in vmlinux or any module.
 func doFindStructTypeByName(s *btf.Spec, name string) (*btf.Struct, *btf.Spec, uint32, error) {
 	if s == nil {
 		return nil, nil, 0, fmt.Errorf("nil BTF: %w", btf.ErrNotFound)
@@ -146,8 +190,13 @@ func doFindStructTypeByName(s *btf.Spec, name string) (*btf.Struct, *btf.Spec, u
 	return findStructTypeByNameFromModule(s, name)
 }
 
-// findStructTypeByNameFromModule walks over the BTF info of loaded modules and
-// searches for struct `name`.
+// findStructTypeByNameFromModule scans all loaded kernel modules and tries
+// to resolve a struct type with the exact name. The iteration uses the base
+// vmlinux spec for string/ID interning as required by btf.Handle.Spec(base).
+//
+// For the first module where AnyTypeByName(name) returns a *btf.Struct,
+// the function returns that struct, the module's *btf.Spec, and its BTF ID.
+// If the type is not found in any module, btf.ErrNotFound is returned.
 func findStructTypeByNameFromModule(base *btf.Spec, name string) (*btf.Struct, *btf.Spec, uint32, error) {
 	it := new(btf.HandleIterator)
 
@@ -184,9 +233,9 @@ func findStructTypeByNameFromModule(base *btf.Spec, name string) (*btf.Struct, *
 	return nil, nil, 0, btf.ErrNotFound
 }
 
-// findStructOpsKernTypes	discovers all kernel-side BTF artefacts related to a given
-//
-// *struct_ops* family identified by its **base name** (e.g. "tcp_congestion_ops").
+// findStructOpsKernTypes discovers all kernel-side BTF artifacts that belong to
+// a given struct_ops, identified by the user-visible base struct name
+// (e.g., "tcp_congestion_ops").
 func findStructOpsKernTypes(userStructType *btf.Struct) (*structOpsKernTypes, error) {
 	spec, err := btf.LoadKernelSpec()
 	if err != nil {
@@ -227,16 +276,14 @@ func findStructOpsKernTypes(userStructType *btf.Struct) (*structOpsKernTypes, er
 	}, nil
 }
 
-// skipModsAndTypedefs returns the **next underlying type** by peeling off a
-// single layer of “type wrappers” in BTF:
-//
-//   - btf.Typedef
-//   - btf.Const
-//   - btf.Volatile
-//   - btf.Restrict
+// skipModsAndTypedefs resolves a single layer of BTF indirection/qualification
+// for the given type within the provided *btf.Spec.
 //
-// If `typ` is already a concrete type (struct, int, ptr, etc.) it is returned
-// unchanged.
+// Behavior:
+//   - Uses s.TypeID(typ) and s.TypeByID(id) to canonicalize the type within s.
+//   - If the resolved type is a Typedef or C qualifier (Const/Volatile/Restrict),
+//     returns its immediate underlying type (one level).
+//   - Otherwise returns the resolved type as-is.
 func skipModsAndTypedefs(s *btf.Spec, typ btf.Type) (btf.Type, error) {
 	typeID, err := s.TypeID(typ)
 	if err != nil {
@@ -269,6 +316,7 @@ func getStructMemberByName(s *btf.Struct, name string) (btf.Member, error) {
 		if member.Name == name {
 			return member, nil
 		}
+		// target kernel struct type (e.g. tcp_congestion_ops).
 	}
 	return btf.Member{}, fmt.Errorf("member %s not found in struct %s", name, s.Name)
 }