From 88036cd6e90f875744840d4ec168d8b50fa54050 Mon Sep 17 00:00:00 2001
From: Jiri Olsa <jolsa@kernel.org>
Date: Tue, 18 Jun 2024 11:34:23 +0000
Subject: [PATCH] tetragon: Add documentation for maps usage

Adding some notes in map.go header about maps usage.

Signed-off-by: Jiri Olsa <jolsa@kernel.org>
---
 pkg/sensors/program/map.go     | 47 ++++++++++++++++++++++++++++++++++
 pkg/sensors/program/program.go | 25 ++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/pkg/sensors/program/map.go b/pkg/sensors/program/map.go
index bb66c55fcb8..b9a6c8f9a93 100644
--- a/pkg/sensors/program/map.go
+++ b/pkg/sensors/program/map.go
@@ -1,6 +1,53 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright Authors of Tetragon
 
+// We allow to define several types of maps:
+//
+//    MapTypeGlobal MapType = iota
+//    MapTypePolicy
+//    MapTypeSensor
+//    MapTypeProgram
+//
+//  Each type defines the maps position in the sysfs hierarchy:
+//
+//    MapTypeGlobal:     /sys/fs/bpf/tetragon/map
+//    MapTypePolicy:     /sys/fs/bpf/tetragon/policy/map
+//    MapTypeSensor:     /sys/fs/bpf/tetragon/policy/sensor/map
+//    MapTypeProgram:    /sys/fs/bpf/tetragon/policy/sensor/program/map
+//
+//  Each type has appropriate helper defined, which sets map's
+//  path to specific level of sysfs hierarchy:
+//
+//    MapTypeGlobal:     MapBuilder
+//    MapTypePolicy:     MapBuilderPolicy
+//    MapTypeSensor:     MapBuilderSensor
+//    MapTypeProgram:    MapBuilderProgram
+//
+//  It's possible to share map between more programs like:
+//
+//     m := MapBuilderSensor("map", prog1, prog2, prog3)
+//
+//  All prog1-3 programs will attach to m1 through:
+//
+//    /sys/fs/bpf/tetragon/policy/sensor/map
+//
+//  The idea is to share map on higher level which denotes to scope
+//  of the map, like:
+//
+//     /sys/fs/bpf/tetragon/map
+//      - map is global shared with all policies/sensors/programs
+//
+//     /sys/fs/bpf/tetragon/policy/map
+//      - map is local for policy, shared by all its sensors/programs
+//
+//     /sys/fs/bpf/tetragon/policy/sensors/map
+//      - map is local for sensor, shared by all its programs
+//
+//     /sys/fs/bpf/tetragon/policy/sensors/program/map
+//      - map is local for program, not shared at all
+//
+//  NOTE Please do not share MapTypeProgram maps, it brings confusion.
+
 package program
 
 import (
diff --git a/pkg/sensors/program/program.go b/pkg/sensors/program/program.go
index c4df3b6e020..835d7d7d1fb 100644
--- a/pkg/sensors/program/program.go
+++ b/pkg/sensors/program/program.go
@@ -3,6 +3,31 @@
 
 package program
 
+// Program sysfs hierarchy
+//
+// Each program is part of policy and sensor and defines PinName
+// which determine its path in sysfs hierarchy, like:
+//
+//   /sys/fs/bpf/tetragon/policy/sensor/program/prog
+//
+// which broken down means:
+//
+//   /sys/fs/bpf/tetragon
+//     - bpf (map) directory
+//
+//   policy/sensor
+//     - defined by sensor.Policy/sensor.Name
+//
+//   program
+//     - defined by program.PinName
+//
+//   prog
+//     - fixed file name (prog_override for override program)
+//
+//  The program.PinPath field hods following portion of the path:
+//     policy/sensor/program
+//  and is initialized when the sensor is loaded.
+
 import (
 	"fmt"