SDK Source Map and Current Rules

🚧 Documentation is under development

The Holoscan SDK guide is currently under active development. Some sections may be incomplete or change without notice.

Questions? Contact RidgeRun or email to support@ridgerun.com.

Holoscan SDK

< >

Contents Pin

• Overview
  • Scope and Release Coverage
  • How Can RidgeRun Help?
  • Holoscan SDK at a Glance
  • Why the API Changed
  • Architecture and Execution Model
• Build, Run, and Validate
  • Build the SDK on AGX Orin
  • Running and Stopping
  • Run SDK Examples
• Core Concepts
  • Operators and Graphs
    • Operator Lifecycle
    • Ports, Samples, and Payload Types
    • Temporal Contracts and Input Selection
    • Building Graphs and Queue Policies
    • Fan-Out, Fan-In, Mux, and Demux
    • Execution Planning and Capacity
      • Automatic Partitioning and Plan Inspection
      • Rates, Queue Sizing, and Derived Tensor Capacity
    • Dynamic Graph Behavior
  • Tensor Data and Memory
    • Tensor Contracts and Memory Types
    • Sensor Payloads and Schemas
    • Allocation Ownership and Tensor Pools
    • Zero-Copy Data Flow and CUDA Stream Ordering
    • Copy Paths and Memory Conversion
    • External Memory: VPI, PVA, NvSci, and DLPack
  • Interprocess Communication
    • Channels and HoloMQ
    • External Endpoints and Endpoint Catalogs
    • Descriptor-Tensor External Topics
    • Standalone ChannelRuntime Clients
    • Dynamic External Peers
• Application and Operator Development
  • Building an HSDK Application
  • Writing a Minimal Operator
  • Typed Parameters and Configuration
  • Reading, Writing, and Forwarding Data
  • Writing Tensor Operators
  • Complete Operator Patterns
  • Authoring Runtime Behavior
  • Runtime Parameter Updates
  • Lifecycle Callbacks and Restart Control
  • Performance and Debugging
  • SDK Source Map
• Operator Reference
  • Core Operators
    • ConvertToOp
    • CopyMakeBorderOp
    • CustomCropOp
    • HolovizOp
    • InferenceOp
    • NonMaximumSuppressionOp
    • NormalizeOp
    • ReformatOp
    • RemapOp
    • ResizeOp
  • Holoscan Camera
    • Overview
    • Build and Installation
    • V4L2CaptureOp
    • SIPLCaptureOp
  • Holoscan RidgeRun
    • Overview
    • Build and Installation
    • ArgusCameraOp
    • V4L2SourceOp
    • V4L2UserPtrSourceOp
    • BgraToPlanarTensorOp
    • RawBayerToBgraOp
    • RawBayerToYoloTensorOp
    • YuyvToBgraOp
    • TensorRtInferenceOp
    • DrmDisplayOp
    • DrmBgraDisplayOp
    • X11DisplayOp
    • CudaCompositorOp
    • DepthColorizerOp
    • FakesinkOp
    • FrameSkipperOp
    • InterprocessSrcOp
    • TestPatternOp
• Migration from Holoscan 4.x
  • Concept Map
  • Applications, Fragments, and Graphs
  • Conditions and Temporal Contracts
  • Code-Level API Evolution
• Examples
  • Core
    • Vision Pipeline Example
    • Managed Run Control Example
    • Automatic Partitioning Example
    • Rate-Aware Ports and Tensor Pool Capacity Example
    • CUDA Green Context Example
    • Inference Example
    • Descriptor-Tensor External Topic Example
    • HoloMQ Example
  • Holoscan Camera
    • SIPL Frame Saver Example
    • SIPL Stereo Monitor Example
  • Holoscan RidgeRun
    • Interprocess External-Endpoint Demo
• Benchmark and Use Cases
  • Holoscan vs GStreamer
    • Overview
    • Capture and Display
      • Execution context
      • G2G latency
      • CPU utilization
      • GPU utilization
      • Process memory (RSS)
      • Results
      • Analysis
    • Capture and Inference
      • Execution context
      • Software interlatency
      • Inference processing time
      • CPU utilization
      • GPU utilization
      • Process memory (RSS)
      • Results
      • Analysis
    • Compare the workloads
    • Implemented Applications
    • Framework Selection
  • Interprocess

SDK Source Map and Current Rules

This reference maps operator declarations, compiler decisions, and runtime behavior to their SDK and camera implementations. Use the links to follow a port, parameter, timing rule, or storage requirement from its public interface into the code that handles it.

For a failure investigated with Performance and Debugging, check the declaration first, then the compiler or runtime path involved. A declaration can be valid on its own while its combination with other graph requirements is rejected.

Operator authoring and run control

What you are working on	Where to look
Declaring an operator and its callbacks	Operator defines the typed operator base. Operator anatomy explains how setup, contracts, lifecycle callbacks, and compute fit together. See Application, Graph, and Operator Anatomy.
Accessing activation state	ExecutionContext provides the activation stream, current parameter snapshot, and runtime controls. See Timing, Graphs, and Runtime Behavior.
Declaring and configuring typed parameters	HOLOSCAN_PARAM_SCHEMA builds the schema; try_decode decodes configuration through that schema. Typed parameters and Parameter schemas provide the authoring background. See Typed Parameters and Configuration.
Admitting parameter updates and restarts	runtime_mutable() and lifecycle_mutable(stage) mark different update routes. Their compiler settings live in ParameterCompileOptions and LifecycleTransactionOptions. See Runtime Parameter Updates and Lifecycle Callbacks and Restart Control.
Inspecting a plan and observing a run	ExecutionPlan exposes the compiled plan; RunSession exposes run control and results. See plan inspection and Running and Stopping.

Ports, tensors, and external peers

These declarations describe what can cross an edge and how storage is acquired and published. Follow them together when checking a tensor path: a matching payload type alone does not establish memory compatibility, stream ordering, or an exportable external boundary.

Question	Source and guide
Which payloads can a port publish?	PublishedPayload defines the supported categories. Raw POD payloads additionally need ChannelTypeIdentity and ChannelPodLayout. See Ports, Samples, and Payload Types.
What does a tensor port require?	TensorInputSpec and TensorOutputSpec describe the tensor contract. See Tensor Contracts and Memory Types.
How does a producer write and publish storage?	TensorOutputLoan owns the output loan; TensorOutputWriteGuard::commit() completes its write transaction before emission. See Writing Tensor Operators.
Which edge policy is being compiled?	ConnectionOptions carries queue, topic, and conversion choices. See Building Graphs and Queue Policies and Copy Paths and Memory Conversion.
How do external clients and tensor topics fit?	External topics, Standalone channel clients, and HoloMQ documentation explain the separate communication layers. See Descriptor-Tensor External Topics and Channels and HoloMQ.

From contracts to runtime behavior

The compiler resolves temporal selection, CUDA graph regions, lifecycle permissions, and resource capacity before execution. The following implementation files are useful when a graph reports an unsupported combination. Read the diagnostic and the surrounding checks together rather than treating one successful sample as permission for every topology.

• temporal_plan_lowering.cpp resolves input selection and missing-data behavior. Pair it with Temporal contracts and Temporal Contracts and Input Selection.
• valid_capture_member_completion() checks completion placement in CUDA graph regions. See Timing, Graphs, and Runtime Behavior for the allowed independent, inputless source case.
• lifecycle_plan_lowering.cpp checks effective lifecycle profiles. See Lifecycle Callbacks and Restart Control for the permissions and bounded capacities a restart requires.
• Performance model explains the relationships between rates, queues, and retained storage. The worked guide is Rates, Queue Sizing, and Derived Tensor Capacity.

Examples to read alongside the API

Small examples make the declarations easier to follow because you can see their complete graph and the result the program checks. The SDK sources below cover planning, run control, memory, and communication as well as inference and image processing.

Related Examples

• automatic_partitioning — inspect partitions without running the graph.
• running_and_stopping — observe completion, failure, and stop requests.
• rate_aware_ports — relate declared rates to derived pool capacity.
• descriptor_tensor_external_topic — exchange descriptor-tensor samples with an external client.
• holomq — follow channel traffic across processes.
• inference and vision_pipeline — model configuration and a checked image-processing chain.

Camera module sources

Camera operators live in a separate module. Its repository branch is hosted under the Holohub repository, but the links here select the camera module itself; its operator and application paths start at the branch root.

Part of the module	Source and guide
Build and platform selection	CMakeLists.txt and sipl_compat.hpp provide the build and SIPL compatibility entry points. See Build and Installation.
V4L2 capture	V4l2CaptureOp::compute() shows capture, copying, and publication. See V4L2CaptureOp.
SIPL capture and service	SIPLCaptureOp::compute() and SIPL service sources show the byte layout and frame lifetime. See SIPLCaptureOp.
Configuration and applications	camera applications contains the frame saver, stereo monitor, and V4L2 workflows. See SIPL Frame Saver Example and SIPL Stereo Monitor Example.

Holoscan SDK

Back to top ↑ < >