docs: update QoS documeent

Add some ideas about a new QoS message.

See also #322947

diff --git a/docs/design/part-qos.txt b/docs/design/part-qos.txt
index f435471..2ab58a0 100644 (file)
--- a/docs/design/part-qos.txt
+++ b/docs/design/part-qos.txt
@@ -31,22 +31,61 @@ QoS event
 The QoS event is generated by an element that synchronizes against the clock. It
 travels upstream and contains the following fields:
 
- - timestamp:  The timestamp on the buffer that generated the QoS
-               event. These timestamps are expressed in total running_time in
-              the sink so that the value is ever increasing.
+ - timestamp, G_TYPE_UINT64:
+      The timestamp on the buffer that generated the QoS event. These timestamps
+      are expressed in total running_time in the sink so that the value is ever
+      increasing.
 
- - jitter:     The difference of that timestamp against the current clock time.
-               Negative values mean the timestamp was on time. Positive values
-              indicate the timestamp was late by that amount.
+ - jitter, G_TYPE_INT64:
+      The difference of that timestamp against the current clock time.  Negative
+      values mean the timestamp was on time. Positive values indicate the
+      timestamp was late by that amount.
 
- - proportion: Long term prediction of the ideal rate relative to
-               normal rate to get optimal quality.
+ - proportion, G_TYPE_DOUBLE:
+      Long term prediction of the ideal rate relative to normal rate to get
+      optimal quality.
 
 The rest of this document deals with how these values can be calculated
 in a sink and how the values can be used by other elements to adjust their
 operations.
 
 
+QoS message
+-----------
+
+Whenever QoS discards a piece of data or affects the quality of the stream, a
+message must be posted by the element that performed the QoS. 
+
+This message can be posted by a sink/src that performs synchronisation against the
+clock or it could be dropped by an upstream element that performs QoS because of
+QOS events received from downstream.
+
+ - live: G_TYPE_BOOLEAN:
+      If the QoS message was dropped by a live element such as a sink or a live
+      source. If the live property is FALSE, the QoS message was generated as a
+      response to a QoS event in a non-live element.
+
+ - timestamp, G_TYPE_UINT64:
+      Running_time of the data that is dropped.
+
+ - jitter, G_TYPE_INT64:
+      The lateness of the buffer. 
+
+ - proportion, G_TYPE_DOUBLE:
+      Long term prediction of the ideal rate.
+
+Optional stats:
+
+ - dropped, G_TYPE_INT64:
+      The total number of dropped buffers since the element went to READY
+      last. -1 if unknown.
+
+ - handled, G_TYPE_INT64:
+      The total number of processed buffers since the element went to READY
+      last. -1 if unknown.
+
+
+
 Collecting statistics
 ---------------------