core-util: avoid abort at redundant fcntl operation failure in abnormal case

[platform/upstream/pulseaudio.git] / PROTOCOL

diff --git a/PROTOCOL b/PROTOCOL
index 0673d86..72d3af3 100644 (file)
--- a/PROTOCOL
+++ b/PROTOCOL
@@ -30,7 +30,7 @@ SHM data transfer support
 
 ### v11, implemented by >= 0.9.7
 
-Reply to to PA_COMMAND_GET_SINK_INPUT_INFO, PA_COMMAND_GET_SINK_INPUT_INFO_LIST gets new field at the end:
+Reply to PA_COMMAND_GET_SINK_INPUT_INFO, PA_COMMAND_GET_SINK_INPUT_INFO_LIST gets new field at the end:
 
  mute
 
@@ -351,6 +351,107 @@ New field in all commands that send/receive profile introspection data
 
 The field is added once for every profile.
 
+## v30, implemented by >= 6.0
+#
+A new protocol mechanism supported: Two ringbuffers in shared memory.
+Pulseaudio fdsem (wrappers around event file descriptors) are used for
+signalling new data.
+The protocol has a new SHM flag telling whether a SHM memblock is writable
+by both sides.
+
+PA_COMMAND_ENABLE_SRBCHANNEL
+First sent from server to client, tells the client to start listening on
+the additional SHM ringbuffer channel.
+This command also has ancillary data (two eventfds attached to it).
+Must be directly followed by a memblock which is the ringbuffer memory.
+When memblock is received by the client, it acks by sending
+PA_COMMAND_ENABLE_SRBCHANNEL back (without ancillary or memblock data).
+
+PA_COMMAND_DISABLE_SRBCHANNEL
+Tells the client to stop listening on the additional SHM ringbuffer channel.
+Acked by client by sending PA_COMMAND_DISABLE_SRBCHANNEL back.
+
+## v31, implemented by >= 9.0
+
+Memfd shared-memory support is now added to PulseAudio as an opt-in feature.
+Add 'enable-memfd=yes' to daemon's configuration to use memfds, instead of
+POSIX shm, by default.
+
+Memfd is a simple memory sharing mechanism, added by the systemd/kdbus
+developers, to share pages between processes in an anonymous, no global
+registry needed, no mount-point required, relatively secure, manner.
+
+PulseAudio memfd support builds the necessary (but not yet sufficient)
+groundwork for a better integration with per-app containers (e.g. xdg-app)
+
+For further details on memfds in general, please check:
+
+  https://dvdhrm.wordpress.com/2014/06/10/memfd_create2/
+  Archived at: http://www.webcitation.org/6gnHTy9Kr
+
+Moreover, for both client and server, the second most-significant bit of
+the version tag is now used to flag memfd SHM support. On the way forward,
+the two most-significant _bytes_ of the version tag are now also reserved
+for flags.
+
+PA_COMMAND_REGISTER_MEMFD_SHMID
+New command that can be sent both ways, from client to server and vice versa.
+This is needed to transfer a memfd pool's blocks without passing its fd every
+time, thus minimizing overhead and avoiding fd leaks.
+
+The registration command above sends a packet with the pool's memfd fd as
+ancillary data. Such packet has an ID that uniquely identifies the pool's
+memfd memory area. Upon arrival, the other end (client or server) creates a
+permanent ID<->memfd mapping.
+
+By doing so, there's need to reference the pool's memfd file descriptor any
+further -- just its ID. Thus both endpoints can then quickly and safely
+close their memfd file descriptors.
+
+## v32, implemented by >= 10.0
+
+Enable memfd transport by default.
+
+This protocol bump was only created to mark 9.0 clients. Although they
+support memfd transport, such older clients has an iochannel bug that would
+break memfd audio if they're run in 32-bit mode over a 64-bit kernel. Thus
+influence these buggy libraries to use POSIX shared memory, by signalling
+memfd support only to 10.0+ clients.
+
+Check commit 451d1d676237c81 for further details.
+
+## v33, implemented by >= 13.0
+
+Added two values to the pa_encoding_t enum:
+
+    PA_ENCODING_TRUEHD_IEC61937 := 7
+    PA_ENCODING_DTSHD_IEC61937 := 8
+
+## v34, implemented by >= 14.0
+
+New fields in the port introspection data (duplicated for all port types:
+sink, source and card ports):
+
+    string availability_group
+    uint32 type
+
+## v35, implemented by >= 15.0
+
+Added new command for communication with objects.
+
+PA_COMMAND_SEND_OBJECT_MESSAGE:
+sends a message to an object identified by an object path
+
+parameters:
+    string object_path - unique path identifying the object
+    string message - message name
+    string message_parameters - additional parameters if required (may be
+                                NULL, which should be treated the same as an
+                                empty string)
+
+The command returns a string, which may be empty or NULL (NULL should be
+treated the same as an empty string).
+
 #### If you just changed the protocol, read this
 ## module-tunnel depends on the sink/source/sink-input/source-input protocol
 ## internals, so if you changed these, you might have broken module-tunnel.