Docs: fixes for images and paths (#1050)

- fixes for images tags (replacement <img> HTML tags with ![] Markdown tag) (working wrong in Sphinx) - images descriptions fixes (removing "png" from image descriptions) - images descriptions fixes (replacing "image" with more meaningful names) - local paths (in the same directory) to pictures/other documents - unified to have no "./" at the beginning
OpenVisualCloud · Jan 29, 2025 · 8fdce09 · 8fdce09
1 parent 5274486
commit 8fdce09
Show file tree

Hide file tree

Showing 10 changed files with 35 additions and 69 deletions.
diff --git a/README.md b/README.md
@@ -58,9 +58,7 @@ MTL also incorporates SIMD (Single Instruction, Multiple Data) for CSC (Color Sp
 
 For the detail design, please refer to [Design Guide](doc/design.md).
 
-<div align="center">
-<img src="doc/png/arch.svg" align="center" alt="/Overall Architecture">
-</div>
+![Overall Architecture](doc/png/arch.svg)
 
 ### 1.3. Ethernet supported
 

diff --git a/doc/aws.md b/doc/aws.md
@@ -18,7 +18,7 @@ Instance example:
 
 ### 2.1. Build and install DPDK & Media Transport Library
 
-Refer to CentOS part of [build.md](./build.md).
+Refer to CentOS part of [build.md](build.md).
 
 ### 2.2. Apply vfio-pci patches
 
@@ -32,7 +32,7 @@ sudo get-vfio-with-wc.sh
 
 ## 3. IOMMU Setting
 
-If you use bare metal, you can turn on IOMMU refer to [run.md](./run.md).
+If you use bare metal, you can turn on IOMMU refer to [run.md](run.md).
 
 If you use VM, set NO-IOMMU mode for vfio after each boot.
 
@@ -72,7 +72,7 @@ dpdk-devbind.py -s
 
 > If no IOMMU support(.nxlarge instance), you have to run it under root user.
 
-Refer to [run.md](./run.md) after section 3.2.
+Refer to [run.md](run.md) after section 3.2.
 
 For single video stream whose bandwidth is grater than 5 Gbps (4k 30fps), arg `--multi_src_port` is needed in Tx app, see 7.3.
 

diff --git a/doc/compliance.md b/doc/compliance.md
@@ -17,41 +17,31 @@ Matrox VERO: narrow gapping
 
 VERO 1080p50 summary
 
-<div align="center">
-<img src="png/compliance/vero_1080p50_summary.png" align="center" alt="VERO 1080p50 summary">
-</div>
+![VERO 1080p50 summary](png/compliance/vero_1080p50_summary.png)
 
 </br>
 
 VERO 1080p50 analysis
 
-<div align="center">
-<img src="png/compliance/vero_1080p50_analysis.png" align="center" alt="VERO 1080p50 analysis">
-</div>
+![VERO 1080p50 analysis](png/compliance/vero_1080p50_analysis.png)
 
 </br>
 
 VERO 1080p50 Cinst per frame
 
-<div align="center">
-<img src="png/compliance/vero_1080p50_cinst_per_frame.png" align="center" alt="VERO 1080p50 Cinst per frame">
-</div>
+![VERO 1080p50 Cinst per frame](png/compliance/vero_1080p50_cinst_per_frame.png)
 
 </br>
 
 VERO 1080p50 VRX per frame
 
-<div align="center">
-<img src="png/compliance/vero_1080p50_vrx_per_frame.png" align="center" alt="VERO 1080p50 VRX per frame.png">
-</div>
+![VERO 1080p50 VRX per frame](png/compliance/vero_1080p50_vrx_per_frame.png)
 
 </br>
 
 Pharbrix 1080p50 analyser: gapping
 
-<div align="center">
-<img src="png/compliance/pharbrix_1080p50_analyser.png" align="center" alt="Pharbrix 1080p50 analyser">
-</div>
+![Pharbrix 1080p50 analyser](png/compliance/pharbrix_1080p50_analyser.png)
 
 </br>
 
@@ -61,40 +51,30 @@ Matrox VERO: narrow gapping
 
 VERO 2160p50 summary
 
-<div align="center">
-<img src="png/compliance/vero_2160p50_summary.png" align="center" alt="VERO 2160p50 summay">
-</div>
+![VERO 2160p50 summay](png/compliance/vero_2160p50_summary.png)
 
 </br>
 
 VERO 2160p50 analysis
 
-<div align="center">
-<img src="png/compliance/vero_2160p50_analysis.png" align="center" alt="VERO 2160p50 analysis">
-</div>
+![VERO 2160p50 analysis](png/compliance/vero_2160p50_analysis.png)
 
 </br>
 
 VERO 2160p50 Cinst per frame
 
-<div align="center">
-<img src="png/compliance/vero_2160p50_cinst_per_frame.png" align="center" alt="VERO 2160p50 Cinst per frame">
-</div>
+![VERO 2160p50 Cinst per frame](png/compliance/vero_2160p50_cinst_per_frame.png)
 
 </br>
 
 VERO 2160p50 VRX per frame.png
 
-<div align="center">
-<img src="png/compliance/vero_2160p50_vrx_per_frame.png" align="center" alt="VERO 2160p50 VRX per frame.png">
-</div>
+![VERO 2160p50 VRX per frame](png/compliance/vero_2160p50_vrx_per_frame.png)
 
 </br>
 
 Pharbrix 2160p50 analyser: gapping
 
-<div align="center">
-<img src="png/compliance/pharbrix_2160p50_analyser.png" align="center" alt="Pharbrix 2160p50 analyser">
-</div>
+![Pharbrix 2160p50 analyser](png/compliance/pharbrix_2160p50_analyser.png)
 
 </br>
diff --git a/doc/design.md b/doc/design.md
@@ -6,9 +6,7 @@ This section provides a detailed design concept of the Media Transport Library,
 
 Similar to other network processing libraries, it consists of a control plane and a data plane. In the data plane, a lockless design is adopted to achieve ultra-high performance.
 
-<div align="center">
-<img src="png/software_stack.png" align="center" alt="Software Stack">
-</div>
+![Software Stack](png/software_stack.png)
 
 ## 2. Core management
 
@@ -23,9 +21,7 @@ With this PMD design, it is expected that a CPU thread will always be utilized t
 By the way, we provide an option `MTL_FLAG_TASKLET_SLEEP` that enables the sleep option for the PMD thread. However, take note that enabling this option may impact latency, as the CPU may enter a sleep state when there are no packets on the network. If you are utilizing the RxTxApp, it can be enable by `--tasklet_sleep` arguments.
 Additionally, the `MTL_FLAG_TASKLET_THREAD` option is provided to disable pinning to a single CPU core, for cases where a pinned core is not feasible.
 
-<div align="center">
-<img src="png/tasklet.png" align="center" alt="Tasklet">
-</div>
+![Tasklet](png/tasklet.png)
 
 ### 2.1. Tasklet design
 
@@ -52,7 +48,7 @@ MTL supports multi-process deployment through the use of SR-IOV. Each process op
 Each instance sends a request to the Manager service, which in return assigns a free core to the instance. The Manager service is also responsible for detecting when an instance disconnects and will subsequently release the associated resources. For more details, please consult the [Manager guide](../manager/README.md)
 
 If the background Manager service is not practical for your setup, there is a fallback method: managing the logical core (lcore) via shared memory. In this approach, all MTL instances loop through a shared memory structure to locate an unused core.
-The instructions for this deprecated method can still be accessed in the [shm_lcore guide](./shm_lcore.md). However, we strongly advise against this method and recommend using the Manager service instead, as it has the capability to detect when any instance has been unexpectedly closed.
+The instructions for this deprecated method can still be accessed in the [shm_lcore Guide](shm_lcore.md). However, we strongly advise against this method and recommend using the Manager service instead, as it has the capability to detect when any instance has been unexpectedly closed.
 
 ### 2.5. The tasklet API for application
 
@@ -210,9 +206,7 @@ During the packet construction process, only the RTP header is regenerated to re
 
 Note that if the currently used NIC does not support the multi-buffer feature, the MTL will need to copy the video frame into the descriptor, resulting in a loss of performance.
 
-<div align="center">
-<img src="png/tx_zero_copy.png" align="center" alt="TX Zero Copy">
-</div>
+![TX Zero Copy](png/tx_zero_copy.png)
 
 #### 4.3.2. ST2110-21 pacing
 
@@ -227,9 +221,7 @@ However, for a 4K 50fps session, the time for one packet is approximately ~1us,
 
 In the case that the rate-limiting feature is unavailable, TSC (Timestamp Counter) based software pacing is provided as a fallback option.
 
-<div align="center">
-<img src="png/tx_pacing.png" align="center" alt="TX Pacing">
-</div>
+![TX Pacing](png/tx_pacing.png)
 
 ### 4.4. ST2110 RX
 
@@ -238,11 +230,9 @@ Once the packet is received and validated as legitimate, the RX session will cop
 
 #### 4.4.1. RX DMA offload
 
-The process of copying data between packets and frames consumes a significant amount of CPU resources. MTL can be configured to use DMA to offload this copy operation, thereby enhancing performance. For detailed usage instructions, please refer to [DMA guide](./dma.md)
+The process of copying data between packets and frames consumes a significant amount of CPU resources. MTL can be configured to use DMA to offload this copy operation, thereby enhancing performance. For detailed usage instructions, please refer to [DMA Guide](dma.md)
 
-<div align="center">
-<img src="png/rx_dma_offload.png" align="center" alt="RX DMA Offload">
-</div>
+![RX DMA Offload](png/rx_dma_offload.png)
 
 ## 5. Control path
 
@@ -365,7 +355,7 @@ Thanks to the plugin, the application can implement ST22 support using the follo
   st22p_tx_free
 ```
 
-The plugin guide can be find at [plugin](./plugin.md), the pipeline detail implementation can be find from [st22_pipeline_tx.c](../lib/src/st2110/pipeline/st22_pipeline_tx.c) and [st22_pipeline_rx.c](../lib/src/st2110/pipeline/st22_pipeline_rx.c).
+The plugin guide can be find at [Plugin Guide](plugin.md), the pipeline detail implementation can be find from [st22_pipeline_tx.c](../lib/src/st2110/pipeline/st22_pipeline_tx.c) and [st22_pipeline_rx.c](../lib/src/st2110/pipeline/st22_pipeline_rx.c).
 
 Sample application code can be find at [tx_st22_pipeline_sample.c](../app/sample/tx_st22_pipeline_sample.c) and [rx_st22_pipeline_sample.c](../app/sample/rx_st22_pipeline_sample.c)
 
@@ -431,7 +421,7 @@ By default, the frame buffer is allocated by MTL using huge page memory, however
 MTL TX and RX will interact with the NIC using these user-defined frames directly. It is the application's responsibility to manage the frame lifecycle because MTL only recognizes the frame address.
 Additionally, it's important to note that if a DPDK-based PMD backend is utilized, the external frame must provide an IOVA address, which can be conveniently obtained using the `mtl_dma_map` API, thanks to IOMMU/VFIO support.
 
-For more comprehensive information and instructions on using these converters, please refer to the [external_frame](./external_frame.md).
+For more comprehensive information and instructions on using these converters, please refer to the [External Frame API Guide](external_frame.md).
 
 ### 6.10. VSync
 
@@ -449,7 +439,7 @@ The ST**_TX_FLAG_USER_TIMESTAMP flag is provided to enable applications to use t
 ### 6.12. SIMD for color space convert
 
 MTL includes an array of built-in SIMD converters, providing high-performance data processing. The implementation details for these converters are available in the MTL library source files [st_avx512.c](../lib/src/st2110/st_avx512.c) and [st_avx512_vbmi.c](../lib/src/st2110/st_avx512_vbmi.c).
-The API for these converters is publicly documented in the header file [st_convert_api.h](../include/st_convert_api.h). For more comprehensive information and instructions on using these converters, please refer to the [convert guide](./convert.md).
+The API for these converters is publicly documented in the header file [st_convert_api.h](../include/st_convert_api.h). For more comprehensive information and instructions on using these converters, please refer to the [Convert Guide](convert.md).
 
 ### 6.13. Runtime update source and destination
 

diff --git a/doc/dma.md b/doc/dma.md
@@ -6,7 +6,7 @@ The Media Transport Library features DMA support to enhance RX video session den
 
 ## 2. DMA driver bind to PMD(vfio-pci) mode
 
-> For how to install DMA device driver on Windows, please refer to [here](./run_WIN.md#46-install-driver-for-dma-devices).
+> For how to install DMA device driver on Windows, please refer to [here](run_WIN.md#46-install-driver-for-dma-devices).
 
 ### 2.1. Locate the available DMA port
 

diff --git a/doc/run.md b/doc/run.md
@@ -167,9 +167,7 @@ Below is the command to convert yuv422p10le file to yuv422rfc4175be10 pg format(
 ```
 
 The yuv422rfc4175be10 files can be viewed by [YUV Viewer tools](https://github.com/IENT/YUView). Below is the custom layout.
-<div align="center">
-<img src="png/yuview_yuv422rfc4175be10_layout.png" align="center" alt="yuview yuv422rfc4175be10 custom layout">
-</div>
+![yuview yuv422rfc4175be10 custom layout](png/yuview_yuv422rfc4175be10_layout.png)
 
 #### 5.1.3. Convert yuv422rfc4175be10 Back to yuv422p10le
 

diff --git a/doc/run_WIN.md b/doc/run_WIN.md
@@ -99,7 +99,7 @@ The previously installed drivers will now be installed for the "Virtual to physi
 
 ### 3.4. Make sure that the driver was installed
 
-![Image](./png/virt2phy.png)
+![Device Manager picture](png/virt2phy.png)
 
 ## 4. Install netuio driver
 
@@ -130,7 +130,7 @@ devcon.exe update netuio.inf "PCI\VEN_8086&DEV_1592"
 
 ### 4.3. Make sure that the driver was installed
 
-![Image](./png/netuio.png)
+![Driver picture](png/netuio.png)
 
 ### 4.4. Get the PCI port name used for MTL
 

diff --git a/doc/sdm_appliance.md b/doc/sdm_appliance.md
@@ -7,10 +7,12 @@ This document  contains instructions for streaming a desktop session to a Intel
 Depicted below are 2 use-case scenario:
 
 1. Synchronous playback scenario where output of a PC/Laptop is streamed via a sending device to the receiver.
- ![Image](./png/mtl-appliance-use-case.png)
+
+![MTL Appliance Use Case Image](png/mtl-appliance-use-case.png)
 
 2. Asynchronous playback - where the sending device is streaming a digital media generated (e.g framebuffer) / stored locally on the device to the receiver.
- ![Image](./png/desktop-streaming-mtl.png)
+
+![Desktop Streaming MTL Image](png/desktop-streaming-mtl.png)
 
 ## 2. Required Hardware
 
@@ -36,7 +38,7 @@ The demo currently works only on Linux. Follow the steps below to install all th
 
 ### Build Media Transport Library (MTL)
 
-- See [build.md](./build.md) to build libmtl on Linux.
+- See [Build Guide](build.md) to build libmtl on Linux.
 
 ### Build ffmpeg (with MTL encoder and decoder)
 

diff --git a/ecosystem/ffmpeg_plugin/README.md b/ecosystem/ffmpeg_plugin/README.md
@@ -91,9 +91,7 @@ Note: The format y210 is not supported by the Ffmpeg plugins for MTL.
 A typical workflow for processing an MTL ST22 compressed stream with FFMpeg is outlined in the following steps: Initially, FFMpeg reads a YUV frame from the input source, then forwards the frame to a codec to encode the raw video into a compressed codec stream. Finally, the codec stream is sent to the MTL ST22 plugin.
 The MTL ST22 plugin constructs the codec stream and transmits it as ST2110-22 RTP packets, adhering to the standard. In addition to the JPEG XS stream, the MTL ST22 plugin is capable of supporting various other common compressed codecs, including H264, H265, and HEVC, among others.
 
-<div align="center">
-<img src="ffmpeg_st22_flow.png" align="center" alt="Tasklet">
-</div>
+![Tasklet](ffmpeg_st22_flow.png)
 
 ### 3.1. St22 output
 

diff --git a/manager/README.md b/manager/README.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-![design](manager_design.svg)
+![MTL Manager Design](manager_design.svg)
 
 MTL Manager is a daemon server designed to operate with root privileges. Its primary role is to manage the lifecycle and configurations of MTL instances. It addresses a variety of administrative tasks, including: