Platforms and Target Profiles

Purpose

Many compiler decisions depend on facts that are not properties of the source language itself. Pointer width, endianness, available CPU instructions, the ABI, MMIO regions, interrupt identities, stack policy and runtime services all depend on the selected target.

Sec resolves those facts once and exposes them through typed compiler models. This prevents the parser, semantic analyzer, static analyses, MLIR lowering, linker, language server and platform library from each inventing their own interpretation of the target.

The platform model therefore provides:

• one canonical identity for the selected architecture and platform;
• one resolved set of CPU and device capabilities;
• one target profile defining enabled facilities and policies;
• one memory, runtime and execution environment;
• one ABI and linking environment;
• deterministic target-specific source selection;
• typed facts for compiler analyses and lowering;
• provenance explaining where each target fact came from.

Portable Semantics

Sec separates language semantics from target capability. A target may be unable to implement a feature, or the current compiler may lack lowering for it, without changing what the feature means in the language.

For example, a target without a native instruction for a wide integer operation does not make the Sec integer type semantically invalid. The compiler may use generated code or a runtime helper when such a realization is available. Likewise, target atomic capabilities describe how an operation can be implemented; they do not redefine the Sec concurrency memory model.

Core Terminology

Five names are especially important because they describe different layers of the build model:

These concepts may be configured together, but they are not interchangeable.

Target

A Target is one logical buildable product.

Examples include:

server
worker
controller
firmware

A Target is not an operating-system and architecture pair. The same logical product may be built for several concrete platforms.

This distinction allows one project to describe a product once while building independent variants for Linux, another hosted system, an RTOS or a bare-metal device where the project permits it.

Variant

A Variant is one concrete requested build configuration for a Target. It is input to platform resolution rather than the final resolved platform model.

A Variant may select or override facts such as:

• operating system;
• architecture;
• ABI;
• CPU;
• CPU features;
• TuneCPU;
• device;
• target profile;
• toolchain intent;
• build-profile settings;
• compile-time parameter overrides.

The resolver validates these selections and converts them into canonical identities before later compiler stages consume them.

Platform

A Platform is the compiler-known system and execution environment selected for a Variant.

Platform identity is semantic. It is not inferred from a source directory name and it is not defined merely because a file happens to exist under a platform-specific folder.

The order is:

resolve platform capabilities
        ↓
resolve compatible target profile
        ↓
freeze CompilationPlan
        ↓
select compatible platform sources

This matters because source files implement the selected platform; they do not define the platform by accident.

BuildProfile

A BuildProfile controls build behavior such as optimization level, debug information, stripping, LTO and instrumentation.

A BuildProfile does not decide whether the target supports:

• threads;
• tasks;
• interrupts;
• MMIO;
• thread-local storage;
• heap allocation;
• a particular ABI.

Those are platform and target-profile facts. In particular, a release-oriented BuildProfile may optimize safety checks only when the compiler can prove they are unnecessary. It may not simply turn mandatory Sec safety into undefined behavior.

TargetProfile

A TargetProfile is the semantic capability, policy and resource profile applied to one concrete CompilationPlan.

It answers questions such as:

• Is heap allocation enabled?
• Are native threads available and enabled?
• Are Sec tasks and a scheduler available?
• May execution detach from its parent?
• Are interrupts and MMIO enabled?
• Which execution contexts may block or allocate?
• Which stack, heap or task-count limits apply?
• How are relevant resource limits enforced?
• Which panic policy applies?

The profile constrains facilities the platform can provide. It cannot enable a capability that the resolved platform or device does not support.

CompilationPlan

A CompilationPlan is the authoritative immutable resolved contract for one Target and one Variant.

A conceptual plan contains facts equivalent to:

CompilationPlan {
    Project
    Target
    Variant
    BuildProfile

    PlatformIdentity
    TargetProfile

    ArchitectureModel
    DeviceModel?
    MemoryEnvironment
    RuntimeEnvironment
    ExecutionEnvironment
    ABIModel
    LinkEnvironment

    SourceSelection
    CompilerTargetSupport

    CompilerOptions
    CompileTimeParameters
}

The exact compiler data structures are implementation details. The important rule is that the same semantic responsibilities exist and are resolved before plan-dependent compiler work begins.

After the plan is frozen, later passes do not reinterpret project configuration or silently query the host to obtain missing facts. A changed configuration creates a new plan.

Multi-Variant Builds

One Target may produce several Variants in a single build operation.

Target: server

Variants:
    linux-amd64
    linux-arm64
    linux-armv7
    another-hosted-amd64

Each Variant receives its own concrete CompilationPlan:

Plan(server, linux-amd64)
Plan(server, linux-arm64)
Plan(server, linux-armv7)
Plan(server, another-hosted-amd64)

Several operating systems or architectures are never represented as one polymorphic plan. Plan-independent compiler results may be shared where safe, while target- dependent results remain associated with the plan that produced them.

Failure of one Variant does not make another Variant semantically invalid, even though the overall build command may report failure when any requested output fails.

Architecture and CPU

Architecture identifies the machine ISA family, such as a canonical Sec identity for AMD64, ARM64, ARM32 or RISC-V32.

Architecture owns machine-level fundamentals such as:

• native word properties;
• pointer representation constraints;
• endianness;
• alignment capabilities;
• legal machine-operation classes;
• architectural capability bounds.

CPU selects the processor or microarchitecture capability baseline that generated code may require.

Architecture = amd64
CPU          = raptorlake

Architecture = arm32
CPU          = cortex-m4

CPU names are registry identities, not language keywords. A CPU selection may enable machine capabilities beyond a generic architecture baseline, but only through canonical feature resolution.

TuneCPU and CPU Features

TuneCPU is an optimization preference. It is intentionally distinct from the CPU capability baseline.

CPU     = generic-amd64
TuneCPU = raptorlake

This may allow instruction scheduling and other optimization choices appropriate to Raptor Lake while generated code remains legal for the generic AMD64 capability baseline.

CPU feature resolution may combine:

• CPU defaults;
• explicitly enabled features;
• explicitly disabled features;
• features required by a concrete Device.

Feature dependencies and conflicts are validated before the plan is frozen.

Device Model

Device is an optional concrete hardware identity. It is separate from CPU because two devices may use the same CPU core while exposing completely different hardware around it.

A Device may define or constrain:

• RAM and flash topology;
• memory maps and MMIO regions;
• interrupt controllers and named interrupt/vector identities;
• peripherals;
• DMA capabilities;
• device-specific registers;
• startup requirements;
• link placement constraints;
• required CPU and CPU features.

If a Device requires a Cortex-M4 CPU and configuration explicitly selects an incompatible CPU, platform resolution fails. A higher-precedence CLI option does not make an impossible hardware combination valid.

A Device identity is not required for an ordinary desktop or server target when the architecture, CPU and platform already provide every required fact.

Resolved Platform Submodels

The CompilationPlan exposes typed resolved submodels so each compiler subsystem can ask the correct owner for a target fact.

MemoryEnvironment

MemoryEnvironment describes target memory topology and capabilities. It may expose facts such as:

• address spaces and stable memory-space identities;
• addressability and pointer-related machine properties;
• alignment requirements;
• MMIO regions;
• static or device memory regions;
• CPU, DMA or accelerator accessibility;
• cacheability and coherence properties where defined.

MemoryEnvironment does not redefine Sec ownership, borrowing, object lifetime or reclamation authority. It provides target facts that those language rules may consume.

MMIO is not inferred by testing whether an integer address “looks like hardware”. Canonical Device or memory metadata identifies MMIO regions for the volatile and hardware-register rules.

RuntimeEnvironment

RuntimeEnvironment describes services available to generated Sec code under the active plan.

Possible service domains include:

• startup;
• panic handling;
• allocation;
• generation tracking;
• thread support;
• task scheduling;
• synchronization helpers;
• thread-local storage;
• numeric and compiler-required lowering helpers.

Sec does not require one complete universal runtime. A valid target may provide only the services needed by its profile and program.

Runtime services that can influence static analysis must expose semantic contracts. A runtime helper may, for example, be known to allocate, block, panic, require a particular execution context or be interrupt-safe.

ExecutionEnvironment

ExecutionEnvironment describes the execution-context model for the active CompilationPlan.

It may contain canonical relations for:

• process execution;
• threads and tasks;
• scheduling;
• interrupts;
• preemption and nesting;
• blocking and reentry;
• execution roots and context transitions;
• physical stack domains.

Static analyses consume these relations instead of guessing behavior from an OS name or raw interrupt priority number.

MayPreempt(A, B)
CannotPreempt(A, B)
MayNest(A, B)
CannotNest(A, B)
MayReenter(A)

Tasks and threads remain distinct. A Sec Task is never assumed to be identical to one operating-system thread merely because a particular runtime chooses such a mapping.

ABI and Link Environment

ABIModel is selected once during platform resolution and then reused by function lowering, FFI, stack reasoning, linking and debugging.

Later compiler stages must not independently infer the ABI from architecture or operating-system spellings.

LinkEnvironment may contain:

• object format;
• symbol model;
• entry convention;
• required startup objects;
• platform libraries;
• relocation model;
• linker capabilities.

Toolchain availability is separate from semantic platform validity. A plan can be semantically valid even when the current compiler host does not have the linker or SDK needed to produce the final binary.

Capability Availability and Activation

Sec deliberately separates whether a target can provide a capability from whether the active profile enables it.

Disabled and Unsupported are different diagnostic causes. A source-level requirement never silently changes a disabled capability to enabled.

Compiler Support vs Platform Support

The target may support a capability before the current compiler can lower it. These facts are kept separate.

Platform:
    Interrupts = Supported

CompilerTargetSupport:
    InterruptLowering = Unsupported

This means the hardware/platform model supports interrupts, but this compiler build cannot yet emit them for the selected target.

A missing lowering stage must not be reported as invalid Sec source or as a hardware limitation. Commands such as semantic checking or static analysis may still be able to operate on a plan for which object emission or linking is not yet implemented.

Target Profile Families

Sec 0.1 defines three compiler-known target-profile families:

Hosted
RTOS
BareMetal

These are policy and capability baselines. They are not operating-system names, CPU identities, ABI identities or runtime products.

• Hosted does not mean every runtime facility is enabled.
• RTOS requires task/scheduler execution, but does not imply native OS threads.
• BareMetal does not mean “no runtime code is allowed”.
• RTOS is not a subtype of Hosted.

A concrete platform or project may derive a profile from one family while selecting additional supported facilities.

Profile Baseline Matrix

Family entries are resolution baselines. A concrete target still resolves each capability against actual platform, device and runtime support.

A baseline of Disabled is not the same as physically unsupported. For example, a concrete BareMetal-derived profile may enable a compatible allocator or scheduler when the selected platform provides the required support and the profile explicitly permits it.

Allocation Policy

Heap allocation is a capability separate from automatic and static storage. Disabling heap allocation does not forbid ordinary local values or static data whose semantics require no dynamic allocation.

Hosted profiles enable supported heap allocation by default. RTOS and BareMetal profiles disable it by default, but a derived concrete profile may enable it when a compatible allocator and failure policy are provided.

Allocation capability and allocation budget are separate. A profile may permit heap allocation while imposing a finite heap budget.

Tasks, Threads and Scheduler

Sec Tasks and native Threads are different execution entities in both the language and target model.

An RTOS profile requires Sec task and scheduler support, but it need not expose native operating-system threads. A Hosted profile may provide both. A BareMetal profile disables task scheduling by default but can derive a profile that enables a supported scheduler.

Detached execution is a separate capability. It may be enabled only when ownership, shutdown, cancellation and cleanup requirements can be satisfied by the selected runtime and execution environment.

Interrupts and MMIO

Hosted profiles disable direct interrupt execution and MMIO/device access by default. RTOS and BareMetal profiles enable these capabilities only when the resolved platform, Device and memory model support them.

When interrupt execution exists, the baseline interrupt context forbids heap allocation and blocking unless a stronger owning interrupt rule explicitly defines a safe alternative.

Interrupt identities, priority/preemption rules, binding, ISR validation and lifecycle are covered in the dedicated interrupt chapter. MMIO, volatile behavior and hardware register transactions are likewise covered by the following hardware chapters.

Safety Cannot Be Weakened

Every Sec 0.1 target-profile family preserves mandatory Sec safety semantics.

A required safety condition must either:

1. be proven statically; or
2. be checked dynamically when execution could otherwise violate it.

A dynamic safety check does not require a large runtime. It may lower to ordinary inline machine code.

Panic Policy

Every valid TargetProfile must provide a defined panic-handling strategy for reachable panic behavior. This does not imply a heavy unwinding runtime.

An execution context may instead forbid panic entirely. When analysis proves that a panic path is reachable from such a context, the program is invalid for that plan.

Lack of a runtime never converts reachable panic into undefined behavior.

Typed Resource Limits

Capability activation answers whether a facility may be used. Resource constraints answer how much of that facility is available or permitted.

Examples include:

MaximumTasks:           ResourceLimit[Count]
MaximumDetachedTasks:   ResourceLimit[Count]
MaximumThreads:         ResourceLimit[Count]
SchedulerQueueCapacity: ResourceLimit[Count]

MainStackBudget:        ResourceLimit[Bytes]
ThreadStackBudget:      ResourceLimit[Bytes]
TaskStackBudget:        ResourceLimit[Bytes]
InterruptStackBudget:   ResourceLimit[Bytes]

StaticStorageBudget:    ResourceLimit[Bytes]
HeapBudget:             ResourceLimit[Bytes]

Resource domains are typed. A count cannot accidentally be compared with a byte budget simply because both happen to use integer storage.

Resolved limits use explicit states:

• KnownLimit(value) — a canonical finite bound is known;
• NoDeclaredLimit — the profile imposes no finite semantic bound;
• UnknownLimit — no usable canonical bound is known.

UnknownLimit is not zero and it is not infinity. In particular, it must never be used as evidence for a positive static proof.

Resource Enforcement

A resource constraint may define an enforcement policy such as:

• StaticRequired — the owning compiler analysis must prove the bound;
• RuntimeEnforced — dynamic use is legal only when exhaustion behavior is defined;
• Advisory — the limit guides diagnostics or optimization without defining validity.

The profile supplies the constraint. Stack analysis, concurrency analysis, ISR analysis or another owning analysis supplies the proof.

Execution Context Policies

Some policies depend on the current execution context rather than one global switch. Compiler-known contexts may include:

Ordinary
Task
Thread
Interrupt
Startup
Shutdown

A context-specific policy may further restrict a globally enabled capability. It cannot make a globally disabled or unavailable capability legal.

Blocking is therefore not represented by one target-wide boolean. A profile may distinguish non-blocking operations, task suspension, thread blocking, indefinite blocking, cancellation-aware waits and other canonical concurrency classes.

Target Profile Resolution

Profile resolution is explicit and ordered.

Profile family baseline
        +
target/platform defaults
        +
device/runtime constraints
        +
project Target/Variant configuration
        +
legal explicit overrides
        ↓
ResolveTargetProfile
        ↓
ValidateTargetProfile
        ↓
ResolvedTargetProfile
        ↓
freeze CompilationPlan

A frozen plan contains resolved facts, not unresolved family dispositions or implicit missing values.

Program requirements are checked against the frozen profile. They do not mutate it.

Derived Profiles

A concrete target, platform, project or implementation may define a profile derived from one canonical Sec family.

ProfileIdentity
BaseProfileLineage
ResolvedFacts

Sec 0.1 uses one base profile lineage. Multiple profile inheritance is not required.

A BareMetal-derived profile may, for example, enable an allocator, scheduler and interrupt support while still remaining a BareMetal profile when its execution model follows the BareMetal baseline.

Overrides and Hard Constraints

Profile precedence runs conceptually from lower to higher authority:

1. canonical profile-family baseline;
2. target/platform defaults;
3. device/runtime-required constraints;
4. project Target/Variant configuration;
5. explicit CLI override where legally overridable.

Precedence chooses among legal alternatives. It does not defeat hard physical or semantic constraints.

For example:

Device:
    Interrupts = Unsupported

cannot be turned into interrupt support by a command-line flag. Likewise, a Device that requires a Cortex-M4 CPU cannot be made compatible with an unrelated CPU simply because the CLI has higher configuration precedence.

Individual profile facts may be classified as:

Overridable
FixedByTarget
FixedByDevice
Derived

Platform Registry

Platform resolution is driven by a canonical typed registry. It may contain definitions for:

• operating systems;
• architectures;
• CPUs and CPU features;
• Devices;
• ABIs;
• TargetProfiles;
• runtime and execution models;
• memory models;
• link models;
• platform source mappings;
• compiler target support.

Aliases are normalized at registry entry. If spellings such as amd64, x86_64 or x64 are accepted as aliases, they resolve to one canonical identity before semantic resolution continues.

Load order, directory enumeration and “last definition wins” are not valid ways to decide platform semantics.

External Platform Definitions

Sec may ship built-in platform definitions, but the architecture also permits declarative external definitions where supported, especially for concrete Devices and platform packages.

Such definitions may describe:

• device identity;
• CPU and required features;
• memory regions;
• interrupt identities and metadata;
• ABI selection;
• platform source mappings;
• runtime availability.

External platform definitions are data, not arbitrary executable compiler plugins. They must be schema-validated, normalized and structurally checked before they become part of a registry snapshot.

Validation includes unknown identities, duplicate definitions, invalid ranges, malformed memory regions, feature conflicts, invalid interrupt metadata and incompatible cross-domain selections.

Platform Source Selection

Platform-specific source selection is derived from the resolved plan. The compiler does not infer semantic platform capabilities from directory names or file presence.

A resolved source selection may contain:

• project sources;
• platform-common sources;
• architecture-specific sources;
• Device-specific sources;
• runtime sources;
• generated sources where defined.

Selection is deterministic when several implementations exist. The registry or source-routing rules decide matching and specificity; filesystem enumeration order does not.

Target constraints attached to source validate compatibility with the already selected plan. They do not choose or mutate the plan themselves.

Cross Compilation and Host Separation

The compiler host and program target are strictly separate environments.

Target facts such as these come from the active CompilationPlan:

• pointer width;
• endianness;
• ABI;
• object format;
• CPU features;
• memory topology;
• platform source selection;
• interrupt model.

They are never silently copied from the machine running the compiler.

The host CPU is not implicitly used as the target CPU. If an explicit native-style request is supported, host discovery is an explicit resolver action whose result is immediately converted to canonical target facts.

Fingerprints and Incremental Caching

Resolved target facts receive stable semantic identities and fingerprints. The compiler may maintain separate dependency domains such as:

ArchitectureFingerprint
LayoutFingerprint
MemoryFingerprint
RuntimeFingerprint
ExecutionFingerprint
ABIFingerprint
LinkFingerprint
OptimizationFingerprint

A fingerprint represents resolved meaning, not file modification time, registry load order or display text.

This lets the compiler invalidate only the results whose dependencies changed. A change to a task limit may invalidate concurrency analysis without invalidating ABI layout. A change to TuneCPU may affect optimization results without changing semantic type checking.

Conservative over-invalidation is permitted. Reusing a stale target-dependent proof is not.

Diagnostics

Platform diagnostics distinguish causes rather than collapsing everything into “invalid target”.

Important categories include:

• unknown platform or device definition;
• invalid configuration;
• unsupported combination;
• supported but disabled capability;
• missing required capability;
• missing platform implementation;
• missing compiler backend support;
• missing toolchain support;
• registry definition error;
• resource bound exceeded;
• required proof unavailable;
• context-policy violation.

Diagnostics retain provenance when it helps explain the failure.

device ExampleDevice requires CPU cortex-m4,
but CPU cortex-m7 was selected by command-line override

This is more useful than reporting a generic “invalid target” error because it tells the programmer which two selections conflict and where the effective choice came from.

LSP and Tooling

The language server uses the same project configuration, platform registry and CompilationPlan resolver as command-line compilation.

The LSP must not silently assume a Hosted profile merely because the editor is running on a desktop computer.

When platform-relevant configuration changes, the LSP can:

1. load the new configuration or registry snapshot;
2. resolve affected CompilationPlans;
3. compare semantic fingerprints;
4. invalidate only dependent state;
5. refresh diagnostics and analysis without requiring an editor restart.

When the new platform configuration is temporarily invalid, positive target-dependent results from the previous plan must not remain presented as current proof.

Relationship to the Hardware Chapters

This chapter defines how target facts are selected and resolved. It does not duplicate the source-level hardware semantics that consume those facts.

The following chapters build on the active CompilationPlan:

• 50 Fixed Addresses, Volatile and Hardware Access — MMIO bindings and physical access;
• 51 Interrupts and ISRs — named interrupt identities, binding, preemption and ISR safety;
• 52 Inline Assembly — explicit target-specific machine operations;
• 53 Program Initialization and Shutdown — startup, shutdown and entry requirements;
• 54 Concurrency and later chapters — execution facilities exposed by the active profile.

The platform model provides the facts. Each owning language rule defines what those facts mean for source code.

Best Practices

• Think of a Target as a product and a Variant as one concrete build of that product.
• Do not use BuildProfile settings to model semantic target capabilities.
• Select the least demanding TargetProfile that still describes the intended environment.
• Keep CPU capability and TuneCPU separate when portable binaries matter.
• Use a concrete Device when memory maps, interrupts or peripherals matter to correctness.
• Do not infer hardware capability from directory names or source-file presence.
• Do not rely on the compiler host as evidence about the target.
• Treat Disabled, Unsupported and Unknown as different states.
• Keep resource limits typed and explicit rather than encoding them as unstructured integers.
• Use profile provenance in diagnostics instead of hiding the effective configuration.
• Keep external platform definitions declarative and reproducible.
• Remember that a valid platform may still lack current compiler lowering or toolchain support.

Summary

• Sec uses one target-independent language model across hosted, RTOS and bare-metal environments.
• A Target is one logical product; a Variant is one concrete requested build configuration.
• A Platform is the compiler-known system and execution environment selected for the Variant.
• BuildProfile controls build behavior; TargetProfile controls semantic capabilities, policies and resource constraints.
• The CompilationPlan is the immutable authoritative resolved contract for one Target and Variant.
• Multi-Variant builds create separate CompilationPlans rather than one polymorphic target model.
• Architecture, CPU, TuneCPU and Device are distinct target concepts.
• TuneCPU may guide optimization but cannot broaden the legal instruction capability set.
• A concrete Device may define memory maps, interrupt identities, peripherals, DMA facts and hard compatibility constraints.
• Memory, runtime, execution, ABI and linking are resolved as distinct platform submodels.
• Capability availability is separate from capability activation.
• Platform support is separate from the current compiler's implementation support.
• Sec 0.1 defines Hosted, RTOS and BareMetal target-profile families.
• Hosted does not mean all facilities enabled; BareMetal does not mean no runtime; RTOS does not imply native threads.
• Mandatory Sec safety semantics cannot be disabled by a target or build profile.
• Every valid profile defines a panic strategy for reachable panic behavior.
• Resource limits are typed and may be statically required, runtime enforced or advisory.
• Program requirements are checked against a frozen profile and never silently enable disabled capabilities.
• Platform definitions are canonical typed data with deterministic validation and provenance.
• Platform-specific source selection follows the resolved plan rather than defining it.
• Cross compilation uses target facts from the plan, never accidental facts from the compiler host.
• Stable semantic fingerprints allow selective incremental invalidation.
• The CLI and LSP use the same canonical platform resolution.