Skip to content

Commit 40c1dcf

Browse files
SakoramSakoram
committed
Add: New API draft
Signed-off-by: Kasiewicz, Marek <[email protected]>
1 parent fcefbb9 commit 40c1dcf

File tree

9 files changed

+1084
-0
lines changed

9 files changed

+1084
-0
lines changed

‎doc/new_API/List-of-changes.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# List of changes in API this draft is trying to present
2+
3+
- Removal of "frame" mode and rtp "mode", modified pipeline mode stays as only API for MTL sessions
4+
5+
- Polymorphic session classes used to reduce code repetition
6+
7+
- Replacing callback with event polling function to notify app about events in lib
8+
9+
- Change of usage pattern for zero copy/external frame mode. A clear separation of two types of
10+
buffer ownership; buffers owned by the library and buffers owned by the application.
11+
12+
- Added stop() start() and shutdown()
13+
14+
> **Note**
15+
> Fields in all structures are dummy, they need to be correctly ported from current API. Also a few functions need to ported.
16+
> This is not a complete API, just a presentation of a few ideas.

‎doc/new_API/buffers-api.h‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
#include <stdbool.h>
2+
#include <stdint.h>
3+
#include <stddef.h>
4+
5+
// Forward declarations
6+
typedef struct media_lib_session_base media_lib_session_t;
7+
typedef struct media_lib_buffer_base media_lib_buffer_t;
8+
9+
// Base buffer structure
10+
typedef struct media_lib_buffer_base {
11+
void* data;
12+
mtl_iova_t iova;
13+
size_t size;
14+
uint64_t timestamp;
15+
uint32_t flags;
16+
uint32_t buffer_id;
17+
void* _internal;
18+
void* user_data;
19+
} media_lib_buffer_base_t;
20+
21+
// Video buffer structure
22+
typedef struct media_lib_video_buffer {
23+
// Base buffer must be the first member
24+
media_lib_buffer_base_t base;
25+
26+
// Video-specific fields
27+
uint32_t width;
28+
uint32_t height;
29+
uint32_t format;
30+
uint32_t stride;
31+
// Additional video buffer fields
32+
} media_lib_video_buffer_t;
33+
34+
// Audio buffer structure
35+
typedef struct media_lib_audio_buffer {
36+
// Base buffer must be the first member
37+
media_lib_buffer_base_t base;
38+
39+
// Audio-specific fields
40+
uint32_t sample_rate;
41+
uint32_t channels;
42+
uint32_t format;
43+
uint32_t samples_per_frame;
44+
// Additional audio buffer fields
45+
} media_lib_audio_buffer_t;
46+
47+
// Type casting macros for safe type conversion
48+
#define MEDIA_LIB_SESSION_TO_VIDEO(session) \
49+
((media_lib_video_session_t*)(session))
50+
51+
#define MEDIA_LIB_SESSION_TO_AUDIO(session) \
52+
((media_lib_audio_session_t*)(session))
53+
54+
#define MEDIA_LIB_BUFFER_TO_VIDEO(buffer) \
55+
((media_lib_video_buffer_t*)(buffer))
56+
57+
#define MEDIA_LIB_BUFFER_TO_AUDIO(buffer) \
58+
((media_lib_audio_buffer_t*)(buffer))

‎doc/new_API/samples/diagrams.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
```mermaid
2+
sequenceDiagram
3+
participant App as Application
4+
participant Session as Media Library Session
5+
6+
participant Network as Network I/O
7+
8+
Note over App,Network: Library-Owned Receiver Flow (sample-rx-lib-owned.c)
9+
10+
App->>Session: media_lib_video_session_create(instance, &rx_config, &session)
11+
Session->>Session: Allocate memory (for NUM_BUFFERS)
12+
Session->>Network: Setup receiver
13+
Session->>Network: Add buffers to receive queue
14+
Session-->>App: Return session handle
15+
16+
loop Receive and process loop
17+
App->>Session: media_lib_buffer_get(session, &buffer, TIMEOUT_MS)
18+
Session->>Network: Wait for data
19+
Network-->>Session: Data received
20+
21+
Session-->>App: Return buffer pointer
22+
23+
Note over App: Process buffer data
24+
25+
App->>Session: media_lib_buffer_put(session, buffer)
26+
27+
Session->>Network: Add buffer to receive queue
28+
Session-->>App: MEDIA_LIB_SUCCESS
29+
30+
end
31+
App->>Session: media_lib_session_shutdown(session)
32+
33+
App->>Session: media_lib_session_destroy(session)
34+
Session->>Session: Deallocate memory
35+
36+
```
37+
38+
```mermaid
39+
sequenceDiagram
40+
participant App as Application
41+
participant Session as Media Library Session
42+
participant Network as Network I/O
43+
44+
Note over App,Network: Library-Owned Transmitter Flow (sample-tx-lib-owned.c)
45+
46+
App->>Session: media_lib_video_session_create(instance, &tx_config, &session)
47+
Session->>Session: Allocate memory (for NUM_BUFFERS)
48+
Session->>Network: Setup transmitter
49+
Session-->>App: Return session handle
50+
51+
52+
loop Acquire, fill, and transmit loop
53+
App->>Session: media_lib_buffer_get(session, &buffer, TIMEOUT_MS)
54+
Session->>Session: Wait for available buffer
55+
Session-->>App: Return available buffer
56+
57+
Note over App: Fill buffer with media data
58+
59+
App->>Session: media_lib_buffer_put(session, buffer)
60+
Session->>Network: Start transmission
61+
Session-->>App: MEDIA_LIB_SUCCESS
62+
Network-->>Session: Transmission complete
63+
Session->>Session: Mark buffer as available
64+
65+
end
66+
67+
App->>Session:media_lib_buffers_flush(session)
68+
App->>Session: media_lib_session_shutdown(session)
69+
App->>Session: media_lib_session_destroy(session)
70+
Session->>Session: Deallocate memory
71+
72+
```
73+
74+
```mermaid
75+
sequenceDiagram
76+
participant App as Application
77+
participant Session as Media Library Session
78+
participant DMA as DMA Memory Manager
79+
participant Events as Event Queue
80+
participant Network as Network I/O
81+
82+
Note over App,Events: App-Owned Receiver Flow (sample-rx-app-owned.c)
83+
84+
App->>Session: media_lib_video_session_create(instance, &rx_config, &session)
85+
Session->>Network: Setup receiver
86+
Session-->>App: Return session handle
87+
88+
App->>App: Allocate memory (for NUM_BUFFERS)
89+
App->>Session: media_lib_mem_register(session, memory, size, &dma_mem)
90+
Session->>DMA: Register memory for DMA
91+
DMA-->>Session: DMA handle
92+
Session-->>App: Return DMA handle
93+
94+
loop Buffer setup loop
95+
App->>App: Create app_buffer_t for each buffer segment
96+
App->>Session: media_lib_buffer_post(session, data, size, app_buffer)
97+
Session->>Network: Add buffer to receive queue
98+
end
99+
100+
loop Poll and process loop
101+
App->>Session: media_lib_event_poll(session, &event, TIMEOUT_MS)
102+
Session->>Events: Check for events
103+
104+
alt Data received
105+
Network->>Session: Data received in posted buffer
106+
Session->>Events: Add BUFFER_RECEIVED event
107+
Events-->>Session: Return event
108+
Session-->>App: Return event with app_buffer context
109+
110+
Note over App: Process buffer data
111+
112+
App->>Session: media_lib_buffer_post(session, buf->data, buf->size, buf)
113+
Session->>Network: Repost buffer for next receive
114+
end
115+
end
116+
117+
Note over App: Cleanup (not shown in sample)
118+
App->>Session: media_lib_mem_unregister(session, dma_mem)
119+
App->>Session: media_lib_session_shutdown(session)
120+
App->>Session: media_lib_session_destroy(session)
121+
122+
```
123+
124+
```mermaid
125+
sequenceDiagram
126+
participant ProducerThread as Producer Thread
127+
participant PollerThread as Poller Thread
128+
participant BufferQueue as Buffer Queue
129+
participant Session as Media Library Session
130+
participant DMA as DMA Memory Manager
131+
participant Events as Event Queue
132+
participant Network as Network I/O
133+
134+
Note over ProducerThread,Events: App-Owned Transmitter Flow (sample-tx-app-owned.c)
135+
136+
Note over ProducerThread,PollerThread: Main thread setup (not shown)
137+
138+
Note over Session,DMA: Memory registration occurs in main thread
139+
140+
loop Producer Thread Loop
141+
ProducerThread->>BufferQueue: dequeue() - Get free buffer
142+
BufferQueue-->>ProducerThread: Return app_buffer_t
143+
Note over ProducerThread: Fill buffer with data
144+
ProducerThread->>Session: media_lib_buffer_post(session, buf->data, buf->size, buf)
145+
Session->>Network: Queue buffer for transmission
146+
end
147+
148+
loop Poller Thread Loop
149+
PollerThread->>Session: media_lib_event_poll(session, &event, TIMEOUT_MS)
150+
Session->>Events: Check for events
151+
alt Transmission complete
152+
Events-->>Session: Return BUFFER_TRANSMITTED event
153+
Session-->>PollerThread: Return event with app_buffer context
154+
PollerThread->>BufferQueue: enqueue(buffer) - Return to free queue
155+
end
156+
end
157+
158+
Note over ProducerThread,PollerThread: Cleanup (not reached in sample)
159+
160+
```

‎doc/new_API/samples/sample-rx-app-owned.c‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
#include <stdio.h>
2+
#include <stdint.h>
3+
#include <stdlib.h>
4+
#include <string.h>
5+
#include "media-lib-api.h"
6+
7+
#define TIMEOUT_MS 1000
8+
#define NUM_BUFFERS 4
9+
#define BUFFER_SIZE 1024
10+
11+
// Application-defined simple buffer structure.
12+
typedef struct {
13+
uint8_t* data; // Pointer to the buffer data.
14+
size_t size; // Size of the buffer.
15+
int id; // Buffer identifier.
16+
} app_buffer_t;
17+
18+
int main(void) {
19+
// Assume instance is created by the library initialization routine.
20+
mtl_handle* instance = /* ... */ NULL;
21+
media_lib_video_session_config_t rx_config = {0};
22+
media_lib_session_t* session = NULL;
23+
uint8_t* registered_memory = NULL;
24+
mtl_dma_mem_handle* dma_mem = NULL;
25+
app_buffer_t* buffers[NUM_BUFFERS];
26+
media_lib_event_t event;
27+
int err;
28+
29+
// Configure a receiver session in user-owned (zero-copy) mode.
30+
rx_config.base.type = MEDIA_LIB_SESSION_RECEIVER;
31+
rx_config.base.ownership = MEDIA_LIB_BUFFER_USER_OWNED;
32+
rx_config.base.buffer_size = BUFFER_SIZE;
33+
rx_config.base.num_buffers = NUM_BUFFERS;
34+
rx_config.base.address = "192.168.1.100";
35+
rx_config.base.port = 1234;
36+
rx_config.base.timeout_ms = TIMEOUT_MS;
37+
rx_config.width = 640;
38+
rx_config.height = 480;
39+
rx_config.framerate = 30;
40+
rx_config.format = 0; // e.g., V_FMT_YUV420P
41+
42+
err = media_lib_video_session_create(instance, &rx_config, &session);
43+
if (err != MEDIA_LIB_SUCCESS) {
44+
printf("Failed to create receiver session\n");
45+
return -1;
46+
}
47+
48+
// Allocate a contiguous block of memory for all buffers.
49+
registered_memory = malloc(NUM_BUFFERS * BUFFER_SIZE);
50+
if (!registered_memory) {
51+
printf("Failed to allocate memory\n");
52+
return -1;
53+
}
54+
err = media_lib_mem_register(session, registered_memory, NUM_BUFFERS * BUFFER_SIZE, &dma_mem);
55+
if (err != MEDIA_LIB_SUCCESS) {
56+
printf("Failed to register memory\n");
57+
free(registered_memory);
58+
return -1;
59+
}
60+
61+
// Create an array of application-defined buffers.
62+
for (int i = 0; i < NUM_BUFFERS; i++) {
63+
buffers[i] = malloc(sizeof(app_buffer_t));
64+
if (!buffers[i]) {
65+
printf("Failed to allocate app_buffer_t for buffer %d\n", i);
66+
// Cleanup omitted for brevity.
67+
return -1;
68+
}
69+
buffers[i]->data = registered_memory + i * BUFFER_SIZE;
70+
buffers[i]->size = BUFFER_SIZE;
71+
buffers[i]->id = i;
72+
// Post the buffer to the library.
73+
// The app_buffer_t pointer is passed as the context.
74+
err = media_lib_buffer_post(session, buffers[i]->data, buffers[i]->size, (void*)buffers[i]);
75+
if (err != MEDIA_LIB_SUCCESS) {
76+
printf("Failed to post rx buffer %d\n", i);
77+
}
78+
}
79+
80+
// Polling loop: process received buffers and repost them.
81+
while (1) {
82+
err = media_lib_event_poll(session, &event, TIMEOUT_MS);
83+
if (err == MEDIA_LIB_SUCCESS) {
84+
if (event.type == MEDIA_LIB_EVENT_BUFFER_RECEIVED) {
85+
// event.ctx is the application context.
86+
app_buffer_t* buf = (app_buffer_t*)event.ctx;
87+
printf("Received buffer id %d, size %ld\n", buf->id, buf->size);
88+
// Process the data in buf->data as needed...
89+
90+
// After processing, repost the buffer back to the library.
91+
err = media_lib_buffer_post(session, buf->data, buf->size, (void*)buf);
92+
if (err != MEDIA_LIB_SUCCESS) {
93+
printf("Failed to repost rx buffer for id %d\n", buf->id);
94+
}
95+
}
96+
}
97+
}
98+
99+
// Cleanup (never reached in this sample).
100+
media_lib_mem_unregister(session, dma_mem);
101+
media_lib_session_shutdown(session);
102+
media_lib_session_destroy(session);
103+
free(registered_memory);
104+
for (int i = 0; i < NUM_BUFFERS; i++) {
105+
free(buffers[i]);
106+
}
107+
return 0;
108+
}

0 commit comments

Comments
 (0)