diff --git a/doc/llr/Link_Layer_Retry_Design.md b/doc/llr/Link_Layer_Retry_Design.md
new file mode 100644
index 00000000000..70c3825c584
--- /dev/null
+++ b/doc/llr/Link_Layer_Retry_Design.md
@@ -0,0 +1,1084 @@
+# SONiC Link Layer Retry
+
+## High Level Design document
+
+
+## Table of contents
+
+- [Revision](#revision)
+- [About this manual](#about-this-manual)
+- [Abbreviations](#abbreviations)
+- [List of Figures](#list-of-figures)
+- [1 Introduction](#1-introduction)
+ - [1.1 Feature Overview](#11-feature-overview)
+ - [1.2 Requirements](#12-requirements)
+ - [1.2.1 Phase I](#121-phase-i)
+ - [1.2.1.1 Configuration and Management Requirements](#1211-configuration-and-management-requirements)
+ - [1.2.1.2 Scalability Requirement](#1212-scalability-requirement)
+ - [1.2.1.3 Warmboot Requirement](#1213-warmboot-requirement)
+ - [1.2.2 Phase II](#122-phase-ii)
+ - [1.2.2.1 Configuration and Management Requirements](#1221-configuration-and-management-requirements)
+- [2 Design](#2-design)
+ - [2.1 LLR Orchestration](#21-llr-orchestration)
+ - [2.1.1 Key Functionalities of LLR Orchestration](#211-key-functionalities-of-llr-orchestration)
+ - [2.1.2 Initial configuration](#212-initial-configuration)
+ - [2.1.3 llrmgrd](#213-llrmgrd)
+ - [2.1.3.1 llr_buffer_lookup.ini Format](#2131-llr_buffer_lookupini-format)
+ - [2.1.4 llrorch](#214-llrorch)
+ - [2.1.5 FlexCounter Orch](#215-flexcounter-orch)
+ - [2.3 SAI API](#23-sai-api)
+ - [2.4 DB schema](#24-db-schema)
+ - [2.4.1 CONFIG_DB](#241-config_db)
+ - [2.4.1.1 New Table LLR_CONFIG](#2411-new-table-llr_config)
+ - [2.4.1.2 New Table LLR_PORT](#2412-new-table-llr_port)
+ - [2.4.1.3 New Table LLR_PROFILE](#2413-new-table-llr_profile)
+ - [2.4.1.4 Extend existing Table FLEX_COUNTER_TABLE to poll LLR port counters](#2414-extend-existing-table-flex_counter_table-to-poll-llr-port-counters)
+ - [2.4.1.5 Configuration Sample](#2415-configuration-sample)
+ - [2.4.2 STATE_DB](#242-state-db)
+ - [2.4.2.1 LLR capabilities](#2421-llr-capabilities)
+ - [2.4.2.2 LLR Port state](#2422-llr-port-state)
+ - [2.4.2.3 LLR Port Counter CAPABILITY](#2423-llr-port-counter-capability)
+ - [2.4.3 FLEX_COUNTER_DB](#243-flex_counter_db)
+ - [2.4.4 COUNTERS_DB](#244-counters_db)
+ - [2.6 CLI](#26-cli)
+ - [2.6.1 LLR Configuration Commands](#261-llr-configuration-commands)
+ - [2.6.1.1 LLR Global Configuration Commands](#2611-llr-global-configuration-commands)
+ - [2.6.1.2 LLR Port Configuration Commands](#2612-llr-port-configuration-commands)
+ - [2.6.1.3 LLR Flex Counter Commands](#2613-llr-flex-counter-commands)
+ - [2.6.2 LLR Show Commands](#262-llr-show-commands)
+ - [2.6.3 LLR Counter Show Commands](#263-llr-counter-show-commands)
+ - [2.7 YANG model](#27-yang-model)
+ - [2.9 Warm/Fast boot](#29-warmfast-boot)
+- [3 Test plan](#3-test-plan)
+ - [3.1 Unit tests](#31-unit-tests)
+ - [3.1.1 Unit Tests and Code Coverage](#311-unit-tests-and-code-coverage)
+
+## Revision
+
+| Rev | Date | Author | Description |
+|:---:|:---------:|:---------------------------: |--------------------|
+| 0.1 |06/Nov/25 | Ravi Minnikanti **(Marvell)** Gnanapriya S **(Marvell)**| Initial Version |
+
+## About this manual
+
+This document presents the design of the UE-LLR feature for SONiC. It details the feature’s requirements, design scope, hardware capability considerations, software architecture, and the impact on associated modules.
+
+## Abbreviations
+
+| Term | Meaning |
+|:------|:------------------------------------------|
+| CRC | Cyclic Redundancy Check |
+| CtlOS | Control Ordered Set |
+| FEC | Forward Error Correction |
+| PCS | Physical Coding Sublayer |
+| LLDP | Link Layer Discovery Protocol |
+| LLR | Link Layer Retry |
+| OA | Orchestration agent |
+| UE | Ultra Ethernet |
+| UEC | Ultra Ethernet Consortium |
+| VS | Virtual Switch |
+
+## List of Figures
+
+[Figure 1: LLR Orchestration Design](#figure-1-llr-orchestration-design)
+[Figure 2: LLR Init Flow](#figure-2-llr-init-flow)
+[Figure 3: LLR Manager Flow](#figure-3-llr-manager-flow)
+[Figure 4: LLR Configuration Flow](#figure-4-llr-configuration-flow)
+[Figure 5: LLR CLI Counter Flow](#figure-5-llr-cli-counter-flow)
+
+# 1 Introduction
+
+## 1.1 Feature Overview
+
+In modern high-speed networks, transient link issues such as CRC errors or uncorrectable FEC errors can result in packet drops. These dropped packets are typically discarded silently by network switches, without any notification to either the sender or receiver, making the loss both invisible and difficult to recover promptly.
+
+Traditionally, recovery from such losses is managed by end-to-end protocols like TCP, which rely on mechanisms such as fast retransmit or timeout-based recovery. However, timeout-driven recovery introduces significant latency, which can severely impact the performance of latency-sensitive applications.
+
+Link Layer Retry (LLR) is introduced to address this challenge by enabling local retransmission of lost frames due to link errors at the data link layer (Layer 2), reducing reliance on higher-layer retransmission and significantly lowering end-to-end latency. This mechanism enhances link reliability and complements existing error recovery strategies in loss-sensitive networks.
+
+LLR works based on the following principles:
+- Frame Tracking: It uses sequence numbers and acknowledgments to monitor the exchange of frames with the link partner.
+- Retransmission Strategy: Upon detecting frame loss, it employs a Go-Back-N retransmission approach to resend the affected frames.
+
+LLR is particularly important in modern data center fabrics and high-speed Ethernet environments, where ultra-low latency and high reliability are critical.
+
+LLR is standardized in UE SPEC v1.0. This design follows SAI conceptual model described in https://github.com/opencomputeproject/SAI/pull/2225
+
+## 1.2 Requirements
+
+### 1.2.1 Phase I
+#### 1.2.1.1 Configuration and Management Requirements
+
+1. **Global Feature Control**: Ability to enable or disable the LLR feature at a global level.
+2. **Configuration Mode**: Support for configuring LLR in static mode globally.
+3. **Per-Interface Control**: Enable or disable LLR individually on each physical ports (LLR feature operates only on ASIC physical ports).
+4. **LLR Profile Generation and Assignment**: LLR profiles are generated using vendor-specific configuration file, and are assigned to ports according to their speed and cable length.
+5. **Port-Level Counters**: Offer detailed LLR counters at the port level for enhanced visibility and debugging.
+6. **Show Commands**: Provide CLI commands to display:
+ - Global LLR configuration status and mode
+ - Per-port LLR configuration status
+ - LLR profiles associated with ports
+ - LLR statistics associated with ports
+7. **Config Commands**: Provide CLI commands to configure:
+ - Global LLR enable/disable
+ - Per-port LLR enable/disable
+ - Extend `counterpoll` to enable/disable and polling interval configuration
+
+#### 1.2.1.2 Scalability Requirement
+
+- **Physical Port Scale**: The LLR feature operates only on physical ports and must be supported across all physical ports in the system.
+
+#### 1.2.1.3 Warmboot Requirement
+
+1. **Planned System Warmboot**: The LLR feature must support **planned system warmboot**.
+2. **SWSS Docker Warmboot**: The LLR feature must also support **SWSS Docker warmboot**.
+
+### 1.2.2 Phase II
+
+#### 1.2.2.1 Configuration and Management Requirements
+
+1. **Configuration Mode**: Support for configuring LLR in **dynamic mode** globally (Not implemented in Phase I).
+2. **LLDP-Based Capability Exchange**: Ability to exchange LLR capabilities with link partners using LLDP control messages (Not implemented in Phase I).
+3. **Administrator-Initiated Exit from FLUSH State**: The LLR transmitter (TX) can be moved out of the FLUSH state through manual intervention by an administrator, based on configuration.
+
+# 2 Design
+
+## 2.1 LLR Orchestration
+
+### 2.1.1 Key Functionalities of LLR Orchestration:
+
+An LLR manager daemon (llrmgrd) and LLR orchestration agent (llrorch) are introduced to enable the feature.
+
+- llrmgrd: Manages global and per-port LLR configuration, auto‑generates profiles from the vendor lookup file, and feeds APPL_DB (dynamic LLDP capability negotiation deferred to a later phase).
+- llrorch: Listens to LLR entries in APPL_DB, creates/updates/removes SAI LLR profile objects, and applies profile bindings and TX/RX enables to ports through syncd/SAI.
+- LLR ini file: A vendor-specific configuration file called `llr_buffer_lookup.ini` used by llrmgrd to generate LLR profiles.
+- LLR stats: FlexCounter support for LLR statistics at the port level.
+
+###### Figure 1: LLR Orchestration Design
+
+
+
+### 2.1.2 Initial configuration
+
+The following initial configurations are handled for LLR
+
+**llrmgrd**
+1. Parse the "llr_buffer_lookup.ini" to construct an internal lookup table that maps the vendor specific LLR profile parameters based on port speed and cable length, this table is used to auto-generate LLR profiles when the feature is enabled.
+2. Subscribes to LLR CONFIG_DB tables for LLR configuration updates.
+3. Subscribes to port-related events, including port speed updates and port cable length change, to dynamically manage LLR profile configurations.
+
+**llrorch**
+1. Orchagent queries the vendor SAI for LLR capabilities information and stores it in STATE_DB.
+2. Retrieved capabilities are referenced when applying LLR configurations to ensure compatibility with the underlying hardware.
+3. Subscribes to LLR tables in APPL_DB to receive updates.
+4. LLR on ports is disabled by default and must be explicitly enabled via configuration.
+
+###### Figure 2: LLR Init Flow
+
+
+### 2.1.3 llrmgrd
+
+`llrmgrd` operates as a daemon within the swss Docker container and is initiated by supervisord, like other swss services.
+ - `llrmgrd` relies on a vendor-supplied ini file named `llr_buffer_lookup.ini` located in the HWSKU directory to generate LLR profile parameters based on port operating speed and cable length.
+ - A WARN log is generated if the `llr_buffer_lookup.ini` file is missing or inaccessible.
+ - Each generated profile is assigned a unique name in the format `llr_buffer___profile`.
+ - `llrmgrd` subscribes to LLR_GLOBAL and LLR_PORT tables in CONFIG_DB to receive LLR global and per-port configuration updates and, depending on the global and per-port LLR state, propagates the relevant LLR configuration to APPL_DB.
+ - If the LLR global configuration mode is set to Static, the configuration is driven by the configuration in CONFIG_DB.
+ - When set to Dynamic, the configuration is driven by the LLDP exchange (This mode is not supported in Phase I of development).
+ - It subscribes to CABLE_LENGTH table in CONFIG_DB for port cable length information. For operational speed updates, it subscribes to the PORT_TABLE in STATE_DB.
+ - When LLR is enabled both globally and on a port, `llrmgrd` generates an LLR profile for the port and writes the corresponding profile to CONFIG_DB.
+ - Additionally, it consumes LLR_PROFILE updates from CONFIG_DB and writes LLR port and profile information to APPL_DB for orchagent consumption.
+
+In Phase I, configurations are carried out statically via CONFIG_DB. Future enhancements may incorporate dynamic capability exchange through LLDP/control-plane interaction with the link partner (Not implemented in Phase I).
+
+#### 2.1.3.1 llr_buffer_lookup.ini Format
+
+`llr_buffer_lookup.ini` is a vendor‑supplied, tabular (whitespace‑separated) configuration file consumed only by `llrmgrd`. Its purpose is to provide vendor specific LLR profile parameter values per operating (port speed, cable length) combination.
+
+Key characteristics:
+* Comment lines start with `#` are ignored.
+* The FIRST TWO columns are mandatory and positional: `speed` and `cable`
+* `outstanding_frames` and `outstanding_bytes` are mandatory columns and must be present to generate a valid profile.
+* Remaining columns are optional and may appear in ANY order; only columns present in the header are parsed. Missing columns mean the vendor does not support / does not set those fields (they are omitted from the generated profile).
+* A dash (`-`) can be used in a cell to explicitly mark an unsupported / unset value for a header column that is otherwise present.
+* The first non‑empty, non‑comment line itself is the header (no leading `#`). It must start with `speed cable`. Parser map column index to field name using this header, allowing flexible ordering and omission.
+
+Field names in `llr_buffer_lookup.ini` maps to CONFIG_DB `LLR_PROFILE` fields. A short alias is used in place of the long name in the `llr_buffer_lookup.ini` header to improve readability. Aliases are only an input convenience.
+
+Profile fields to ini header mapping:
+```
+max_outstanding_frames <-> outstanding_frames (number of frames)
+max_outstanding_bytes <-> outstanding_bytes (bytes)
+max_replay_timer <-> replay_timer (ns)
+max_replay_count <-> replay_count (count)
+pcs_lost_timeout <-> pcs_lost_timeout (ns)
+data_age_timeout <-> data_age_timeout (ns)
+ctlos_spacing_bytes <-> ctlos_spacing (bytes)
+init_action <-> init_action (best_effort | block | discard)
+flush_action <-> flush_action (best_effort | block | discard)
+```
+
+Sample file snippet:
+```
+speed cable outstanding_frames outstanding_bytes replay_timer replay_count pcs_lost_timeout data_age_timeout ctlos_spacing init_action flush_action
+400000 3m 4096 262144 5000 3 50000 20000 2048 best_effort block
+400000 10m 4096 262144 5500 3 55000 24000 2048 best_effort block
+800000 3m 8192 524288 5000 3 50000 20000 2048 best_effort best_effort
+800000 10m 8192 524288 5500 3 55000 24000 2048 best_effort discard
+```
+
+Vendors may omit any unsupported field other than the `outstanding_frames` and `outstanding_bytes` by removing the column from the header; the manager will skip setting that attribute. This flexible format allows heterogeneous hardware capabilities without requiring code changes.
+
+###### Figure 3: LLR Manager Flow
+
+
+### 2.1.4 llrorch
+
+`llrorch` applies LLR configurations received from APPL_DB to SAI, only if vendor support is confirmed through a capability query.
+
+ 1. On start, query vendor capabilities once and write them to `SWITCH_CAPABILITY|switch` table (STATE_DB).
+ 2. `llrorch` subscribes to LLR tables in APPL_DB and then pushes the configuration to ASIC_DB to configure SAI.
+ 3. For each APPL_DB, LLR_PROFILE and LLR_PORT event: create/update/remove the corresponding SAI LLR profile object and bind/unbind it to the port.
+ 4. Reflect per‑port LLR operational status into STATE_DB LLR_PORT table.
+ 5. Support for automatic reinitialization of the LLR-enabled port from the "FLUSH" state (reinit_on_flush) is not included in Phase I. As a result, llrorch will always set the attribute SAI_LLR_PROFILE_ATTR_RE_INIT_ON_FLUSH to TRUE when creating the SAI LLR profile object.
+
+###### Figure 4: LLR Configuration Flow
+
+
+### 2.1.5 FlexCounter Orch
+
+LLR per-port statistics support is achieved using the existing Flex Counter framework. A new flex counter group named LLR is introduced for this purpose.
+
+High-level flow:
+
+1. During initialization, portsorch in orchagent queries the vendor SAI for LLR port statistics capabilities.
+2. portsorch writes the reported per-counter capability information into STATE_DB.
+3. For each port with LLR enabled (per CONFIG_DB) portsorch evaluates the capability set:
+ - If at least one LLR statistic is supported, portsorch programs the relevant statistic IDs to enable LLR counters.
+4. The flex counter thread in syncd polls SAI at the configured interval and updates LLR counters to COUNTERS_DB.
+5. The CLI (show llr counters / show llr counters detailed) consults STATE_DB to determine which counters are supported and displays only those; unsupported counters are shown as N/A.
+
+## 2.3 SAI API
+The following table lists the SAI APIs used and their relevant attributes.
+
+**SAI attributes which shall be used for Link Layer Retry:**
+
+| API | Function | Attribute |
+|:-------|:---------------------------------|:-------------------------------------------------------|
+| PORT | sai_query_attribute_capability | SAI_PORT_ATTR_LLR_MODE_LOCAL |
+| | | SAI_PORT_ATTR_LLR_MODE_REMOTE |
+| | | SAI_PORT_ATTR_LLR_PROFILE |
+| | | SAI_OBJECT_TYPE_PORT_LLR_PROFILE to get |
+| | | supported SAI_LLR_PROFILE_ATTR_XXX |
+| | sai_query_stats_capability | SAI_OBJECT_TYPE_PORT |
+| | | to get list of SAI_PORT_STAT_LLR_XXX |
+
+**SAI Port-LLR-profile Attributes:**
+
+| API | Function | Attribute |
+|:------------|:--------------------------------------|:-------------------------------------------------------|
+| LLR_PROFILE | sai_create_port_llr_profile_fn | SAI_PORT_LLR_PROFILE_ATTR_OUTSTANDING_FRAMES_MAX |
+| | sai_remove_port_llr_profile_fn | SAI_PORT_LLR_PROFILE_ATTR_OUTSTANDING_BYTES_MAX |
+| | sai_set_port_llr_profile_attribute_fn | SAI_PORT_LLR_PROFILE_ATTR_REPLAY_TIMER_MAX |
+| | sai_get_port_llr_profile_attribute_fn | SAI_PORT_LLR_PROFILE_ATTR_REPLAY_COUNT_MAX |
+| | | SAI_PORT_LLR_PROFILE_ATTR_PCS_LOST_TIMEOUT |
+| | | SAI_PORT_LLR_PROFILE_ATTR_DATA_AGE_TIMEOUT |
+| | | SAI_PORT_LLR_PROFILE_ATTR_INIT_LLR_FRAME_ACTION |
+| | | SAI_PORT_LLR_PROFILE_ATTR_FLUSH_LLR_FRAME_ACTION |
+| | | SAI_PORT_LLR_PROFILE_ATTR_RE_INIT_ON_FLUSH (only TRUE) |
+| | | SAI_PORT_LLR_PROFILE_ATTR_CTLOS_TARGET_SPACING |
+
+**SAI Port Attributes:**
+
+| API | Function | Attribute |
+|:-------|:---------------------------------|:-------------------------------------------------------|
+| PORT | sai_set_port_attribute_fn | SAI_PORT_ATTR_LLR_MODE_LOCAL |
+| | sai_get_port_attribute_fn | SAI_PORT_ATTR_LLR_MODE_REMOTE |
+| | | SAI_PORT_ATTR_LLR_PROFILE |
+
+
+**SAI LLR statistics Attributes per port:**
+
+| API | Function | Attribute |
+|:-------|:---------------------------------|:-------------------------------------------------------|
+| PORT | sai_get_port_stats_fn | SAI_PORT_STAT_LLR_TX_INIT_CTL_OS |
+| | | SAI_PORT_STAT_LLR_TX_INIT_ECHO_CTL_OS |
+| | | SAI_PORT_STAT_LLR_TX_ACK_CTL_OS |
+| | | SAI_PORT_STAT_LLR_TX_NACK_CTL_OS |
+| | | SAI_PORT_STAT_LLR_TX_DISCARD |
+| | | SAI_PORT_STAT_LLR_TX_OK |
+| | | SAI_PORT_STAT_LLR_TX_POISONED |
+| | | SAI_PORT_STAT_LLR_TX_REPLAY |
+| | | SAI_PORT_STAT_LLR_RX_INIT_CTL_OS |
+| | | SAI_PORT_STAT_LLR_RX_INIT_ECHO_CTL_OS |
+| | | SAI_PORT_STAT_LLR_RX_ACK_CTL_OS |
+| | | SAI_PORT_STAT_LLR_RX_NACK_CTL_OS |
+| | | SAI_PORT_STAT_LLR_RX_ACK_NACK_SEQ_ERROR |
+| | | SAI_PORT_STAT_LLR_RX_OK |
+| | | SAI_PORT_STAT_LLR_RX_POISONED |
+| | | SAI_PORT_STAT_LLR_RX_BAD |
+| | | SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_GOOD |
+| | | SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_POISONED |
+| | | SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_BAD |
+| | | SAI_PORT_STAT_LLR_RX_MISSING_SEQ |
+| | | SAI_PORT_STAT_LLR_RX_DUPLICATE_SEQ |
+| | | SAI_PORT_STAT_LLR_RX_REPLAY |
+
+## 2.4 DB schema
+
+### 2.4.1 CONFIG_DB
+
+#### 2.4.1.1 New Table LLR_CONFIG
+```abnf
+; defines schema for global LLR configuration
+
+key = LLR_CONFIG | GLOBAL ; Global LLR configuration table
+
+; field = value
+state = "enabled" / "disabled" ; Feature admin state
+ ; - "enabled" : Enable Link Layer Retry
+ ; - "disabled" : Disable Link Layer Retry
+ ; Default: "disabled"
+mode = "static" / "dynamic" ; Network configuration mode
+ ; - "static" : Use statically configured per-port enable
+ ; - "dynamic": derive per-port enables via LLDP negotiation (Not implemented in Phase I)
+```
+
+#### 2.4.1.2 New Table LLR_PORT
+```abnf
+; defines schema for LLR Port configuration attributes
+key = LLR_PORT | ifname ; Interface name (Ethernet only). Must be unique
+
+; field = value
+local_state = "enabled" / "disabled" ; Per-port LLR local state
+ ; Implementation maps to setting SAI_PORT_ATTR_LLR_MODE_LOCAL. Default: "disabled" (only applied when mode == "static")
+remote_state = "enabled" / "disabled" ; Per-port LLR remote state
+ ; Implementation maps to setting SAI_PORT_ATTR_LLR_MODE_REMOTE. Default: "disabled" (only applied when mode == "static")
+profile = 1*64VCHAR ; LLR Profile name bound to the port (auto-generated)
+
+```
+
+#### 2.4.1.3 New Table LLR_PROFILE
+```abnf
+; defines schema for LLR profile configuration attributes
+
+key = LLR_PROFILE | profile_name ; Auto-generated per (speed, cable_len)
+ ; naming: "llr_buffer___profile"
+ ; Must be unique
+
+; field = value
+max_outstanding_frames = 1*10DIGIT ; Replay buffer size (frames) max unacknowledged
+ ; frames. Range 0..524288.
+max_outstanding_bytes = 1*10DIGIT ; Replay buffer size (bytes) max unacknowledged bytes. Range 0..4294967295
+max_replay_count = 1*3DIGIT ; Max replays (1..255). Default: 1
+max_replay_timer = 1*10DIGIT ; Maximum replay timer (ns) delay before
+ ; retransmission trigger. Range 0..65535
+pcs_lost_timeout = 1*10DIGIT ; Maximum PCS lost status duration (ns).
+ ; Range 0..4290000000
+data_age_timeout = 1*10DIGIT ; Maximum age a frame may reside in replay buffer (ns). Range 0..4290000000
+ctlos_spacing_bytes = 1*5DIGIT ; Target spacing between CtlOS msgs (ACK/NACK).
+ ; Range 400..16384. Default: 2048
+
+init_action = "discard" / ; TX behavior in INIT state.
+ "block" / ; Default: "best_effort"
+ "best_effort"
+
+flush_action = "discard" / ; TX behavior in FLUSH state.
+ "block" / ; Default: "best_effort"
+ "best_effort"
+
+```
+
+#### 2.4.1.4 Extend existing Table FLEX_COUNTER_TABLE to poll LLR port counters
+```abnf
+; defines schema for LLR Port STAT counter configuration attributes
+key = FLEX_COUNTER_TABLE | countername ; Flex counter name. Must be unique
+ ; countername == LLR for LLR counter
+
+; field = value
+FLEX_COUNTER_STATUS = "enable" / "disable" ; Flex counter status for LLR Port counters
+FLEX_COUNTER_DELAY_STATUS = "true" / "false" ; Flex counter delay status
+POLL_INTERVAL = 1*10DIGIT ; Flex counter polling interval
+
+```
+
+#### 2.4.1.5 Configuration Sample
+
+**LLR_CONFIG Table**
+```json
+{
+ "LLR_CONFIG|GLOBAL": {
+ "value": {
+ "state": "enabled",
+ "mode": "static"
+ }
+ }
+}
+```
+
+**LLR_PORT Table**
+```json
+{
+ "LLR_PORT|Ethernet0": {
+ "value": {
+ "local_state": "enabled",
+ "remote_state": "enabled",
+ "profile": "llr_buffer_800000_40m_profile"
+ }
+ }
+}
+```
+
+**LLR_PROFILE Table**
+```json
+{
+ "LLR_PROFILE|llr_buffer_800000_40m_profile": {
+ "value": {
+ "max_outstanding_frames": "4096",
+ "max_outstanding_bytes": "262144",
+ "max_replay_count": "3",
+ "max_replay_timer": "5000",
+ "pcs_lost_timeout": "50000",
+ "data_age_timeout": "20000",
+ "ctlos_spacing_bytes": "2048",
+ "init_action": "best_effort",
+ "flush_action": "best_effort"
+ }
+ }
+}
+```
+
+**FLEX_COUNTER_TABLE (LLR)**
+```json
+{
+ "FLEX_COUNTER_TABLE|LLR": {
+ "value": {
+ "FLEX_COUNTER_STATUS": "enable",
+ "FLEX_COUNTER_DELAY_STATUS": "false",
+ "POLL_INTERVAL": "10000"
+ }
+ }
+}
+```
+
+### 2.4.2 STATE_DB
+
+#### 2.4.2.1 LLR capabilities
+LLR capability is published in the existing STATE_DB table `SWITCH_CAPABILITY|switch`.
+
+**Schema:**
+```abnf
+key = SWITCH_CAPABILITY | switch ; must be unique
+
+; field = value
+LLR_CAPABLE = "true" / "false" ; specifies whether switch supports LLR feature
+LLR_SUPPORTED_PROFILE_ATTRIBUTES = "OUTSTANDING_BYTES_MAX, OUTSTANDING_FRAMES_MAX, REPLAY_TIMER_MAX, REPLAY_COUNT_MAX, PCS_LOST_TIMEOUT, DATA_AGE_TIMEOUT, CTLOS_TARGET_SPACING"
+```
+
+**Sample JSON:**
+```json
+"SWITCH_CAPABILITY|switch": {
+ "value": {
+ "LLR_CAPABLE": "true",
+ "LLR_SUPPORTED_PROFILE_ATTRIBUTES": "OUTSTANDING_BYTES_MAX, OUTSTANDING_FRAMES_MAX, REPLAY_TIMER_MAX, REPLAY_COUNT_MAX, PCS_LOST_TIMEOUT, DATA_AGE_TIMEOUT, CTLOS_TARGET_SPACING"
+ ...
+ }
+}
+```
+
+#### 2.4.2.2 LLR Port state
+New Table - LLR_PORT
+```abnf
+; defines schema for LLR Port level state details
+key = LLR_PORT | ifname ; Interface name (Ethernet only). Must be unique
+
+; field = value
+state = "" / "ok" ; Port has LLR enabled and LLR profile bound
+
+```
+
+**Sample JSON:**
+```json
+"LLR_PORT|Ethernet0": {
+ "value": {
+ "state": "ok"
+ }
+}
+```
+
+#### 2.4.2.3 LLR Port Counter CAPABILITY
+
+```abnf
+; LLR counter capabilities uses existing PORT_COUNTER_CAPABILITIES table
+; Key pattern:
+key = PORT_COUNTER_CAPABILITIES | LLR
+; field = value
+"LLR Counter field" = "true" / "false" ; specifies whether specific LLR port counter is supported
+```
+
+**Sample JSON:**
+
+```json
+"PORT_COUNTER_CAPABILITIES|LLR": {
+ "value": {
+ "LLR_TX_INIT_CTL_OS": "true",
+ "LLR_TX_INIT_ECHO_CTL_OS": "true",
+ "LLR_TX_ACK_CTL_OS": "true",
+ "LLR_TX_NACK_CTL_OS": "true",
+ "LLR_RX_INIT_CTL_OS": "true",
+ "LLR_RX_INIT_ECHO_CTL_OS": "true",
+ "LLR_RX_ACK_CTL_OS": "true",
+ "LLR_RX_NACK_CTL_OS": "true"
+ }
+}
+```
+
+### 2.4.3 FLEX_COUNTER_DB
+
+LLR per-port statistics configuration is stored in FLEX_COUNTER_DB with the PORT_COUNTER_ID_LIST specifying which LLR counters to collect.
+
+```abnf
+; defines schema for LLR Port counter configuration in FLEX_COUNTER_DB
+key = FLEX_COUNTER_TABLE:LLR_PORT_STAT_COUNTER:oid:
+
+; field = value
+PORT_COUNTER_ID_LIST = "SAI_PORT_STAT_LLR_TX_INIT_CTL_OS,
+ SAI_PORT_STAT_LLR_TX_INIT_ECHO_CTL_OS,
+ SAI_PORT_STAT_LLR_TX_ACK_CTL_OS,
+ SAI_PORT_STAT_LLR_TX_NACK_CTL_OS,
+ SAI_PORT_STAT_LLR_TX_DISCARD,
+ SAI_PORT_STAT_LLR_TX_OK,
+ SAI_PORT_STAT_LLR_TX_POISONED,
+ SAI_PORT_STAT_LLR_TX_REPLAY,
+ SAI_PORT_STAT_LLR_RX_INIT_CTL_OS,
+ SAI_PORT_STAT_LLR_RX_INIT_ECHO_CTL_OS,
+ SAI_PORT_STAT_LLR_RX_ACK_CTL_OS,
+ SAI_PORT_STAT_LLR_RX_NACK_CTL_OS,
+ SAI_PORT_STAT_LLR_RX_ACK_NACK_SEQ_ERROR,
+ SAI_PORT_STAT_LLR_RX_OK,
+ SAI_PORT_STAT_LLR_RX_POISONED,
+ SAI_PORT_STAT_LLR_RX_BAD,
+ SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_GOOD,
+ SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_POISONED,
+ SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_BAD,
+ SAI_PORT_STAT_LLR_RX_MISSING_SEQ,
+ SAI_PORT_STAT_LLR_RX_DUPLICATE_SEQ,
+ SAI_PORT_STAT_LLR_RX_REPLAY"
+```
+
+**Sample FLEX_COUNTER_DB Entry:**
+```json
+{
+ "FLEX_COUNTER_TABLE:LLR_PORT_STAT_COUNTER:oid:0x1000000000009": {
+ "type": "hash",
+ "value": {
+ "PORT_COUNTER_ID_LIST": "SAI_PORT_STAT_LLR_TX_INIT_CTL_OS,SAI_PORT_STAT_LLR_TX_INIT_ECHO_CTL_OS,SAI_PORT_STAT_LLR_TX_ACK_CTL_OS,SAI_PORT_STAT_LLR_TX_NACK_CTL_OS,SAI_PORT_STAT_LLR_TX_DISCARD,SAI_PORT_STAT_LLR_TX_OK,SAI_PORT_STAT_LLR_TX_POISONED,SAI_PORT_STAT_LLR_TX_REPLAY,SAI_PORT_STAT_LLR_RX_INIT_CTL_OS,SAI_PORT_STAT_LLR_RX_INIT_ECHO_CTL_OS,SAI_PORT_STAT_LLR_RX_ACK_CTL_OS,SAI_PORT_STAT_LLR_RX_NACK_CTL_OS,SAI_PORT_STAT_LLR_RX_ACK_NACK_SEQ_ERROR,SAI_PORT_STAT_LLR_RX_OK,SAI_PORT_STAT_LLR_RX_POISONED,SAI_PORT_STAT_LLR_RX_BAD,SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_GOOD,SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_POISONED,SAI_PORT_STAT_LLR_RX_EXPECTED_SEQ_BAD,SAI_PORT_STAT_LLR_RX_MISSING_SEQ,SAI_PORT_STAT_LLR_RX_DUPLICATE_SEQ,SAI_PORT_STAT_LLR_RX_REPLAY"
+ }
+ }
+}
+```
+
+### 2.4.4 COUNTERS_DB
+
+LLR per-port statistics are stored in the existing COUNTERS_DB Port Counters table.
+
+## 2.6 CLI
+
+**LLR CLI Commands**
+```
+ - config llr {enable|disable}
+ - config llr mode {static|dynamic} (dynamic Not implemented in Phase I)
+ - config llr interface local-state {enabled|disabled} // only applicable when mode == static
+ - config llr interface remote-state {enabled|disabled} // only applicable when mode == static
+
+ - show llr
+ - show llr interface [interface-name]
+ - show llr profile [profile-name]
+ - show llr counters [interface-name]
+ - show llr counters detailed [interface-name]
+
+ - counterpoll llr enable
+ - counterpoll llr interval 1000
+
+ - sonic-clear llr counters
+ - sonic-clear llr counters interface
+```
+
+### 2.6.1 LLR Configuration Commands
+### 2.6.1.1 LLR Global Configuration Commands
+The following command enable/disable LLR feature:
+
+**LLR Feature state - Enable/Disable**:
+```bash
+## config llr
+
+config
+|--- llr
+```
+The following command configures LLR mode:
+
+**Global LLR Config mode **:
+```bash
+## config llr mode
+
+config
+|--- llr
+ |--- mode
+```
+### 2.6.1.2 LLR Port Configuration Commands
+The following commands allow enabling/disabling LLR local and remote states separately on a port. As per the UE SPEC, local_state is set when LLDP negotiation determines that both ends of a link support LLR, and remote_state is set when negotiation receives indication from the remote end of the link that its local_state has been set to ON.
+
+In static mode, handling local_state and remote_state enablement sequence across the link parts is the responsibility of the network administrator.
+
+**Enable/Disable LLR per Port**:
+```bash
+## config llr interface local-state {enabled|disabled}
+## config llr interface remote-state {enabled|disabled}
+
+config
+|--- llr
+ |--- interface
+ |--- local-state {enabled|disabled}
+ |--- remote-state {enabled|disabled}
+
+### 2.6.1.3 LLR Flex Counter Commands
+**The following command updates LLR Flex counter configuration:**
+```bash
+counterpoll llr enable
+counterpoll llr interval 1000
+```
+
+### 2.6.2 LLR Show Commands
+```bash
+## show llr
+
+LLR Global Information:
+ LLR state : Enable
+ LLR Config Mode : Static
+
+```
+
+```bash
+## show llr interface
+
+LLR Interface Configuration
+----------------------------
+
+PORT LLR Local State LLR Remote State LLR PROFILE
+---------- ----------------- ------------------ ------------------------------
+Ethernet1 enabled disabled llr_buffer_800000_40m_profile
+Ethernet2 enabled enabled llr_buffer_800000_40m_profile
+Ethernet3 enabled enabled llr_buffer_100000_100m_profile
+```
+
+```bash
+## show llr profile llr_buffer_800000_40m_profile
++---------------------------------------+--------------+
+| LLR Profile: llr_buffer_800000_40m_profile |
++=======================================+==============+
+| Maximum Outstanding Frames | 4096 |
++---------------------------------------+--------------+
+| Maximum Outstanding Bytes | 262144 |
++---------------------------------------+--------------+
+| Maximum Replay Count | 3 |
++---------------------------------------+--------------+
+| Maximum Replay Timer(ns) | 5000 |
++---------------------------------------+--------------+
+| PCS Lost Status Timeout(ns) | 50000 |
++---------------------------------------+--------------+
+| Data Age Timeout(ns) | 20000 |
++---------------------------------------+--------------+
+| CTLOS Spacing Bytes | 2048 |
++---------------------------------------+--------------+
+| Init Action | best_effort |
++---------------------------------------+--------------+
+| Flush Action | best_effort |
++---------------------------------------+--------------+
+
+```
+```bash
+## The following command shows llr counter configuration:
+
+## counterpoll show
+Type Interval (in ms) Status
+------------ ------------------ --------
+LLR_STAT 10000 enable
+```
+
+### 2.6.3 LLR Counter Show Commands
+
+###### Figure 5: LLR CLI Counter Flow
+
+
+
+```bash
+## The following command shows LLR counter statistics:
+
+## show llr counters
+
+## show llr counters Ethernet0
+
+Port Rx STATUS RX_INIT RX_INIT_ECHO RX_ACK RX_NACK RX_OK RX_BAD RX_POISONED RX_REPLAY
+--------- ------- ------- ------------ ------ ------- ----- ------ ----------- ---------
+Ethernet0 Enable 1 1 15000 0 35000 0 0 0
+
+Port Tx STATUS TX_INIT TX_INIT_ECHO TX_ACK TX_NACK TX_OK TX_DISCARD TX_POISONED TX_REPLAY
+--------- ------- ------- ------------ ------ ------- ----- ---------- ----------- ---------
+Ethernet0 Enable 1 1 15000 0 35000 0 0 0
+
+```
+
+```bash
+# show llr counters detailed Ethernet0
+
+LLR Counters - Ethernet0
+-----------------------
+LLR_INIT CtrlOS Transmitted ............................. 1
+LLR_INIT_ECHO CtrlOS Transmitted ............................. 1
+LLR_ACK CtrlOS Transmitted ............................. 35000
+LLR_NACK CtrlOS Transmitted ............................. 0
+
+LLR Frames Transmitted OK .................................... 35000
+LLR Frames Transmitted as poisoned ........................... 0
+LLR Frames Discarded at Transmit ............................. 0
+LLR Tx Replay Triggered Count ................................ 0
+
+LLR_INIT CtrlOS Received ................................ 1
+LLR_INIT_ECHO CtrlOS Received ................................ 1
+LLR_ACK CtrlOS Received ................................ 15000
+LLR_NACK CtrlOS Received ................................ 0
+LLR_ACK/NACK CtrlOS Received with SeqNum error .............. 0
+
+LLR Frames Received OK ....................................... 35000
+LLR Frames Received as Poisoned .............................. 0
+LLR Frames Received as Bad ................................... 0
+LLR Rx Replay Detect Count ................................... 0
+
+LLR Frames Received OK with expected seq num ................. 0
+LLR Frames Received Poisoned with expected seq num ........... 0
+LLR Frames Received Bad with expected seq num ................ 0
+
+LLR Frames Received with Unexpected seq num .................. 0
+LLR Frames Received with Duplicate seq num ................... 0
+
+```
+
+```bash
+##The following command clear LLR counter per specific interface or for all interfaces:
+#sonic-clear llr counters
+#sonic-clear llr counters interface
+```
+## 2.7 YANG model
+
+Existing YANG model `sonic-port.yang` at `sonic-buildimage/src/sonic-yang-models/yang-models`
+will be extended with a new schema in order to provide support for Link Layer Retry.
+
+New typedef `port_llr_frame_action` will be added to `sonic-types.yang`.
+
+**Skeleton code:**
+```yang
+module sonic-types {
+ ...
+ typedef port_llr_frame_action {
+ type enumeration {
+ enum discard;
+ enum block;
+ enum best_effort;
+ }
+ description
+ "Action for LLR TX Frame: discard, block, or best_effort.";
+ }
+ ...
+} /* end of module sonic-types */
+```
+
+**Skeleton code:**
+```yang
+module sonic-llr-port {
+ yang-version 1.1;
+
+ namespace "http://github.com/sonic-net/sonic-llr-port";
+ prefix llr-port;
+
+ revision 2025-06-27 {
+ description
+ "Initial Revision";
+ }
+
+ container sonic-llr-port {
+
+ container LLR_PORT {
+
+ list PORT_LIST {
+
+ key "port";
+
+ leaf port {
+ type leafref {
+ path /port:sonic-port/port:PORT/port:PORT_LIST/port:name;
+ }
+ }
+
+ leaf local_state {
+ type stypes:admin_mode;
+ default disabled;
+ description "Enable LLR local state on the port.";
+ }
+
+ leaf remote_state {
+ type stypes:admin_mode;
+ default disabled;
+ description "Enable LLR remote state on the port.";
+ }
+
+ leaf llr_profile {
+ type leafref {
+ path "/llr-profile:sonic-llr-profile/llr-profile:LLR_PROFILE/llr-profile:LLR_PROFILE_LIST/llr-profile:name";
+ }
+ description
+ "LLR Profile configuration to be applied for the port's LLR mechanism when LLR capabilities are exchanged.";
+ }
+
+ } /* end of list PORT_LIST */
+
+ } /* end of container LLR_PORT */
+
+ } /* end of container sonic-llr-port */
+
+} /* end of module sonic-llr-port */
+```
+
+New YANG model `sonic-llr-profile.yang` will be added in order to provide support for Port Link Layer Retry.
+
+**Skeleton code:**
+```yang
+
+module sonic-llr {
+ yang-version 1.1;
+
+ namespace "http://github.com/sonic-net/sonic-llr";
+ prefix llr;
+
+ import sonic-types {
+ prefix stypes;
+ }
+
+ revision 2025-06-27 {
+ description
+ "Initial revision.";
+ }
+
+ description
+ "YANG model for global Link Layer Retry configuration.";
+
+ container sonic-llr {
+ description
+ "Top-level container for LLR global configuration.";
+
+ container LLR_CONFIG {
+ description
+ "LLR global configuration.";
+
+ container GLOBAL {
+ description
+ "Global LLR state and mode settings.";
+
+ leaf state {
+ type stypes:admin_mode;
+ default disabled;
+ description
+ "LLR feature state.";
+ }
+
+ leaf mode {
+ mandatory true;
+ type enumeration {
+ enum static;
+ enum dynamic;
+ }
+ description "LLR configuration mode; Dynamic is LLDP driven and static is manually configured.";
+ }
+ }
+ /* end of container GLOBAL */
+ }
+ /* end of container LLR_CONFIG */
+ }
+ /* end of container sonic-llr */
+}
+/* end of module sonic-llr */
+
+module sonic-llr-profile {
+
+ yang-version 1.1;
+
+ namespace "http://github.com/sonic-net/sonic-llr-profile";
+ prefix llr-profile;
+
+ import sonic-types {
+ prefix stypes;
+ }
+
+ description "LLR Profile YANG Module for SONiC OS";
+
+ revision 2025-06-27 {
+ description
+ "Initial Revision";
+ }
+
+ container sonic-llr-profile {
+
+ container LLR_PROFILE {
+ list LLR_PROFILE_LIST {
+ key "name";
+
+ leaf name {
+ type string;
+ description "LLR Profile name.";
+ }
+
+ leaf max_outstanding_frames {
+ mandatory true;
+ type uint32 {
+ range "0..524288";
+ }
+ description "Replay buffer size (frames) maximum unacknowledged frames at sender.";
+ }
+
+ leaf max_outstanding_bytes {
+ mandatory true;
+ type uint32;
+ description "Replay buffer size (bytes) maximum unacknowledged bytes at sender.";
+ }
+
+ leaf max_replay_count {
+ type uint8 {
+ range "1..255";
+ }
+ default 1;
+ description "Maximum number of times a replay is performed.";
+ }
+
+ leaf max_replay_timer {
+ type uint32 {
+ range "0..65535";
+ }
+ default 0;
+ description "Maximum Replay Timer value in nanoseconds. This timer holds the time delay, before initiating replay from sender, post timer expiry, LLR initiates replay of unacknowledged frames";
+ }
+
+ leaf pcs_lost_timeout {
+ type uint32 {
+ range "0..4290000000";
+ }
+ default 0;
+ description "Maximum value for Port PCS lost status timer in nanoseconds. This value represents maximum duration for a port PCS status can be lost, post timer expiry, LLR state transitions into FLUSH state. Support for non-zero values is optional depending on platform implementation.";
+ }
+
+ leaf data_age_timeout {
+ type uint32 {
+ range "0..4290000000";
+ }
+ default 0;
+ description "Maximum value for data age timeout in nanoseconds. This value represents the maximum time that data can reside in the replay buffer. Post timer expiry, LLR declares the replay data is too old and invalid for retransmission";
+ }
+
+ leaf ctlos_spacing_bytes {
+ type uint16 {
+ range "400..16384";
+ }
+ default 2048;
+ description "Target spacing (bytes) between control ordered set messages.";
+ }
+
+ leaf init_action {
+ type stypes:port_llr_frame_action;
+ default "best_effort";
+ description "TX frame action in INIT state.";
+ }
+
+ leaf flush_action {
+ type stypes:port_llr_frame_action;
+ default "best_effort";
+ description "TX frame action in FLUSH state.";
+ }
+
+ }
+ /* end of list LLR_PROFILE_LIST */
+ }
+ /* end of container LLR_PROFILE */
+ }
+ /* end of top level container */
+}
+/* end of module sonic-llr-profile */
+```
+
+The sonic-flex_counter.yang will be updated with new containers to reflect the proposed CONFIG_DB changes as shown below,
+
+**Skeleton code:**
+```yang
+container FLEX_COUNTER_TABLE {
+ ...
+ container LLR {
+ leaf FLEX_COUNTER_STATUS {
+ type flex_status;
+ }
+ leaf FLEX_COUNTER_DELAY_STATUS {
+ type flex_delay_status;
+ }
+ leaf POLL_INTERVAL {
+ type poll_interval;
+ }
+ }
+}
+```
+
+## 2.9 Warm/Fast boot
+
+No special handling is required for warmboot or fastboot.
+
+# 3 Test plan
+
+## 3.1 Unit tests
+
+### 3.1.1 Unit Tests and Code Coverage
+
+Unit Tests and code coverage will be implemented for below components:
+- CLI (sonic-utilities)
+- llrmgrd
+- llrorch
+- Yang Validation (sonic-yang-models)
+
+**LLR Unit Tests on VS**
+
+1. Enable LLR on a single interface (static mode)
+ - Verify a new LLR_PROFILE entry in CONFIG_DB.
+ - Verify the same LLR_PROFILE entry in APPL_DB.
+ - Verify LLR_PORT| in CONFIG_DB with profile set to the auto‑generated name (contains speed and cable length).
+
+2. Disable LLR on that interface
+ - Verify that LLR_PROFILE entry removed from CONFIG_DB.
+ - Verify the LLR_PROFILE entry removed from APPL_DB.
+ - Verify the profile field absent in LLR_PORT| (or entry removed if empty).
+
+3. Disable the global LLR feature (LLR_CONFIG|GLOBAL state=disabled)
+ - Verify no LLR_PROFILE entries in CONFIG_DB and APPL_DB.
+ - Verify no profile field in LLR_PROFILE PORT entries in CONFIG_DB.
+ - Verify no LLR_PORT entries in STATE_DB.
+
+4. Verify published capabilities
+ - STATE_DB SWITCH_CAPABILITY|switch: LLR_CAPABLE = true.
+ - All supported LLR profile attribute names present in LLR_SUPPORTED_PROFILE_ATTRIBUTES.
+ - STATE_DB PORT_COUNTER_CAPABILITIES|LLR contains expected LLR counter capability flags.
+
+5. Re‑enable LLR on the interface (static mode) and verify ASIC programming
+ - Verify ASIC_DB port object shows SAI_PORT_ATTR_LLR_MODE_LOCAL = true and SAI_PORT_ATTR_LLR_MODE_REMOTE = true.
+ - Verify ASIC_DB contains an LLR profile object with expected attribute values.
+ - Verify STATE_DB LLR_PORT| state = "ok".
+
+6. Disable LLR again on the interface
+ - Verify ASIC_DB shows SAI_PORT_ATTR_LLR_MODE_LOCAL = false and SAI_PORT_ATTR_LLR_MODE_REMOTE = false.
+ - Verify ASIC_DB LLR profile object removed (if not referenced by another port).
+ - Verify STATE_DB LLR_PORT| state field absent (or entry removed).
+
+
+
diff --git a/doc/llr/images/llr_cli_counter_flow.svg b/doc/llr/images/llr_cli_counter_flow.svg
new file mode 100644
index 00000000000..764486f77fc
--- /dev/null
+++ b/doc/llr/images/llr_cli_counter_flow.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/doc/llr/images/llr_config_flow.svg b/doc/llr/images/llr_config_flow.svg
new file mode 100644
index 00000000000..db97e37b18b
--- /dev/null
+++ b/doc/llr/images/llr_config_flow.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/doc/llr/images/llr_init_flow.svg b/doc/llr/images/llr_init_flow.svg
new file mode 100644
index 00000000000..463d583840c
--- /dev/null
+++ b/doc/llr/images/llr_init_flow.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/doc/llr/images/llr_llrmgrd_flow.svg b/doc/llr/images/llr_llrmgrd_flow.svg
new file mode 100644
index 00000000000..869efafaff9
--- /dev/null
+++ b/doc/llr/images/llr_llrmgrd_flow.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/doc/llr/images/llr_orchestration_design.svg b/doc/llr/images/llr_orchestration_design.svg
new file mode 100644
index 00000000000..31acc3e3a6b
--- /dev/null
+++ b/doc/llr/images/llr_orchestration_design.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/doc/llr/llr_buffer_lookup.ini.sample b/doc/llr/llr_buffer_lookup.ini.sample
new file mode 100644
index 00000000000..e57ca095a90
--- /dev/null
+++ b/doc/llr/llr_buffer_lookup.ini.sample
@@ -0,0 +1,40 @@
+############################################################################################################
+# llr_buffer_lookup.ini
+#
+# Vendor‑supplied lookup table used by llrmgrd to auto‑generate LLR_PROFILE entries per (speed, cable_len).
+#
+# Format is similar to port_config.ini:
+# * Plain text, whitespace separated columns.
+# * Lines beginning with '#' are comments and ignored.
+# * First two columns are mandatory and positional:
+# - speed: interface speed in Mb/s (e.g. 100000, 400000, 800000)
+# - cable_length: cable length string as used in CONFIG_DB PORT table (e.g. 1m, 3m, 40m)
+# * Remaining columns are optional and MAY appear in any order. A vendor lists only the
+# fields it supports; absent columns are treated as unsupported / not configured.
+# * If a column is present but a particular row wants to skip the value, use '-' (dash) to denote unset.
+# * Duplicate (speed, cable_length) rows are not allowed.
+#
+# Column Header Rule (Option 4):
+# First non-empty, non-comment line IS the header (no leading '#').
+# Header must start with: speed cable_length
+# You may use either long field names or short aliases (mixing allowed).
+# Subsequent lines are data rows.
+#
+# Alias mapping (long <-> short):
+# max_outstanding_frames <-> outstanding_frames
+# max_outstanding_bytes <-> outstanding_bytes
+# max_replay_timer <-> replay_timer
+# max_replay_count <-> replay_count
+# pcs_lost_timeout <-> pcs_lost_timeout
+# data_age_timer <-> data_age_timer
+# ctlos_spacing_bytes <-> ctlos_spacing
+# init_action <-> init_action
+# flush_action <-> flush_action
+#
+# Example values (illustrative only):
+
+speed cable outstanding_frames outstanding_bytes replay_timer replay_count pcs_lost_timeout data_age_timer ctlos_spacing init_action flush_action
+400000 3m 4096 262144 5000 3 50000 20000 2048 best_effort block
+400000 10m 4096 262144 5500 3 55000 24000 2048 best_effort block
+800000 3m 8192 524288 5000 3 50000 20000 2048 best_effort best_effort
+800000 10m 8192 524288 5500 3 55000 24000 2048 best_effort discard