manual: Add a section on rebuild of the "next" branch.

NEWS update.

vss: Avoid potential double free of FEC parameters.

If an error occurs in initialize_fec_client() we free the FEC parameter
structure but do not invalidate it. It's both easier and safer to
free this struct just before allocating it.

Introduce per group slice sizes.

While the FEC parameters k and n are fixed, the size of a FEC slice may
be different for each FEC group. This patch exploits this freedom and
implements variable sized FEC slices for the DCCP and UDP transports.

Two new functions, compute_group_size() and compute_slice_size(),
are introduced which try to compute an optimal size for the entire
FEC group and the slice size of the group respectively.

The group size is chosen such that the group duration is approximately
150ms. Larger values cause too much latency while smaller groups use
the available bandwidth ineffectively. Several contraints such as
the maximal packet size are taken into account when computing the
group size.

Once the group size is known, a suitable slice size is chosen. It
should be as small as possible to avoid unnecessary FEC calculations
but must be large enough to guarantee that the k data slices suffice
to encode the header (if needed) and the data chunk(s).

vss: need_audio_header(): Change return value to bool.

Obviously an equivalent transformation.

Compute the maximal chunk size only once.

This patch adds the new field max_chunk_size to struct audio_file_data.
It is initialized in the afs process when the chunk table is saved,
just before the audio_file_data struct is passed to the server process.

The vss code benefits from this change since it can just use the
new information rather than calling afh_get_largest_chunk_size()
to recompute the maximal chunk size from scratch whenever a new
client connects.

Since vss.c was the only user of afh_get_largest_chunk_size(), we
may kill this function.

Replace ROUND_UP by DIV_ROUND_UP and use it everywhere.

Remove FEC parameter max_slice_bytes.

It is no longer a FEC parameter as its value is determined at runtime
from the MPS of the connection.

So replace ->max_slice_bytes of struct fec_client_parms by the new
->mps field of struct fec_client.

Simplify vss_send().

Replace check for stream_chunk < 0 by state == NONE.

The two conditions are equivalent but the latter form is more readable.

FEC initialization cleanups.

Initialization was performed in two steps: During vss_send and
during compute_next_fec_slice(). This patch moves the init code
for fec clients to the single location.

vss: Cleanup num_slices().

This makes num_slices() take ints rather than uint8_t arguments which
avoids nasty integer overflows and allows to drop the result parameter
since the result is now contained in the return value.

Moreover, num_slices() now takes the number of redundant slices as
an additional argument, so that this value has to be comuted only
once in the caller.

NEWS update.

Merge branch 't/sched_cleanups'

para.h, recv.h: Move parts marked with \cond to bottom.

This makes doxygen much happier as it does no longer spit out
tons of messages like

warning: documentation for unknown define VERSION_TEXT found.

Merge remote branch 'refs/remotes/fml/master'

udp_recv: Add missing line break in log messages.

Also reduce the line length a bit and fix a whitespace issue.

para.h: Fix typo in comment.

web/download.html: Recommend downloading the snapshot tarball.

Mention that the git tarball is a snapshot of the master branch and
is expected to be more stable than the released versions.

NEWS update.

dccp_send: Fix com_off().

This command made para_server sefgault due to the FEC client structure being
freed, but still used from vss.c. Fix this serious bug by first calling
dccp_shutdown_clients() which removes all FEC clients.

audiod: Handle crashes of para_server more robustly.

In case para_server dies unexpectedly, para_audiod may still have a partial status
item in the buffer tree node of the client task which can lead to a busy loop.

Fix this by flushing the input queue and invalidate the current audio format to prevent
recreating a buffer tree before the status task resumes.

There is already flush_input_queue() in buffer_tree.c but that can't be called by audiod.c
as it is a static function. Make it public and rename it to btr_drain() which is shorter and
more to the point and has the usual btr_ prefix.

Add missing documentation of moods_event_handler() and btr_free_node().

connect_local_socket(): Silence noisy debug message.

sched: Use built-in instead of open-coded timeout helpers.

In many places, sched_min_delay() or sched_request_timeout() are
open-coded.  Use the corresponding helpers from sched.c instead and
rename the "timeout" parameter of sched_request_timeout() to avoid
warnings on old gcc versions.

Improve filter help text.

- Mention that "efficient way" means zero-copy,

- Replace "filter options" by "options for a particular filter",

- Replace -f by --filter.

net: Rename create_remote_socket() connect_local_socket().

It's all about local unix domain sockets, so avoid the word
"remote". Also, this function does not create the socket special
in /var/paraslash.

fade: Print the mixer device.

Otherwise the error "no such file" can be misleading.

afh: Chunk numbers are zero-based.

This makes the numbers match what para_server logs.

Fix an invalid-free-bug in the ogg audio format handler code.

In process_ogg_packets(), if ogg_sync_pageout() fails, we jmp to
the out label where "stream" is being freed by ogg_stream_clear()
without being initialized.

This causes para_afh and para_server to segfault in libogg:

*** glibc detected *** para_afh: munmap_chunk(): invalid pointer: 0x6f890d42 ***
======= Backtrace: =========
/usr/lib/glibc/lib/libc.so.6(+0x66e5a)[0x6f712e5a]
/usr/lib/glibc/lib/libc.so.6(+0x68021)[0x6f714021]
/usr/local/lib/libogg.so.0(ogg_stream_clear+0x2f)[0x6f891adf]
para_afh[0x804cb52]
para_afh[0x804cbeb]
para_afh[0x804ce59]
para_afh[0x804be71]
para_afh[0x804a97c]
/usr/lib/glibc/lib/libc.so.6(__libc_start_main+0xd9)[0x6f6c2c79]
para_afh[0x8049991]

Fix this bug by returning the error code directly rather than jumping
to "out".

new codename, reset version to git

the paraslash-0.4.4 release tarball

paraslash 0.4.4

manual: Minor cleanups.

- Mention that OGG/Speex also needs periodic audio file headers, reword
this sentence.

- para_write now understands formats != 16 bit, so remove this restriction also
from the documentation. Also mention that the sample format is being read from
the wav header, if present.

- Typo fix.

Fix typo in write_common.h.

This makes doxygen happy again.

Rename some variables to avoid warnings on old gcc versions.

Fortunately, gcc-4 no longer warns on these. However, gcc-3.3 is still supported
for compiling paraslash, so rename "index" to "idx" and "conf" to "config" to get
rid of warnings of the form

wmadec_filter.c:1013: warning: declaration of `index' shadows a global declaration

Add documentation of ->free_config() while we're at it.

NEWS update.

Merge branch 't/speex'

Merge branch 't/error2'

NEWS update

Merge branch 't/bits_per_sample'

alsa: Add a missing "goto again" statement.

Without this the return value of btr_node_status() might be incorrect
as the wrong minimal input queue size was used.

Add a reference to the speex home page.

Also mention the name of the speex Debian package.

Add missing documentation of rfds parameter of accept_sender_client().

Fixes

/home/work/maan/scm/paraslash/send_common.c:260: warning: The following parameters of accept_sender_client(struct sender_status *ss, fd_set *rfds) are not documented:
parameter 'rfds'

aacdec: Fix a brown paper bag bug.

Oops, we were using PARA_MAX() instead of PARA_MIN() to determine
the number of bytes to convert in the next run.  This silly bug could
lead to a segfault in the aacdec filter. Moreover, the assertion in
buffer_tree.c that would have caught the bug was _also_ b0rken.

But it's not my fault. I blame Grover of the Sesame street for both
bugs. He did explain the difference between near and far, although
this knowledge is next to useless for a programmer. And he did not
say a single word about MIN and MAX, or true and false. No wonder
such bugs happen.

Make autoconf-2.66 happy.

This removes more lines than it adds and avoids the following warning;

configure.ac:689: warning: AC_DEFINE_UNQUOTED: `
configure.ac:689:       result=
configure.ac:689:       for i in $status_items; do
configure.ac:689:               result="$result SI_$(echo $i | tr 'a-z' 'A-Z')' is not a valid preprocessor define value

Use a perl script to create error2.h

This is *much* faster than the shell code in configure. Perl is
required anyway for help2man, so this patch does not introduce
additional requirements on the build system.

Add support for the speex codec.

This patch adds support for yet another audio format: speex, a
CELP-based codec designed for speech.

As speex is usually used in combination with the OGG container format,
we only support this combination. The new OGG/Speex audio format
handler provides a callback structure for the generic ogg code,
very similar to the OGG/Vorbis audio format handler.

The new speex code is split over three source files: spx_afh.c contains
the audio format handler, spxdec_filter.c the decoder and spx_common.c
common functions used by both audio format handler and decoder.

Many thanks to Jean-Marc Valin, the author of the reference
implementation of the speex decoder. Reusing parts of his code made
it easy to support speex within paraslash.

ogg: Separate ogg from vorbis code.

This moves vorbis-independent code from ogg_afh.c to the new file
ogg_afh_common.c so that it can be used also for the speex audio
format handler that is added by subsequent patches.

The patch introduces a generic callback structure which contains a
function pointer used to call back into the vorbis code once for each
of the three ogg packets of the audio file header.

Kill supported_audio_formats().

It's kind of silly to have a function that just returns a constant string
which is known at compile time. Even more silly is to contruct this string
using an #ifdef for each optional audio format when we already
constructed the space-separated list of supported audio formats during
configure.

So just use AC_DEFINE_UNQUOTED() in configure.ac to make the
list of supported audio formats available via config.h and get rid of
supported_audio_formats(). Rename it to SERVER_AUDIO_FORMATS
and kill a useless space character while we're at it.

Content complete, some external links missing.

Cosmetics: Rename samplerate to sample_rate.

A subsequent patch will introduce sample_format which looks much nicer
than sampleformat. So let's use the underscored variant throughout.

write: Support audio formats != 16 bit little endian.

This adds the new --sample_format option to para_write and teaches
the check_wav_task to read the sample format from the wav header
rather than assuming 16 bit little endian.

The alsa, oss and osx writers all ask the upper buffer tree nodes
for the current audio format. For para_write the check_wav task
answers this query by using the value given at the command line,
looking at the wav header, or using 16 bit little endian as the
default answer.

For para_audiod, the current decoder answers this query. In this
case the audio format is either 16 bit little endian or 16 bit
big endian, depending on the endianness of the machine.

write: Make get_btr_value() return void.

Asking upper buffer tree nodes for the sample rate and the channels
count should never fail, because the writer only asks if there is
already some output data to process.

So, replace the tests by assertions, change the return value
of get_btr_value() to void and fix up all callers accordingly.
This simplifies the code a bit.

Introduce decoder_execute().

All four decoders support the same two commands: "sample_rate"
and "channels". This patch adds a public function to filter_common.c
which implements these two commands and is called by all decoders.
This allows to kill four copies of code with identical functionality.

Deduplicate --channels and --sample-rate.

These options are identical for all writers. Moreover, they only
make sense for para_write but are ignored for para_audiod.

So move these options from the writer-specific ggo file to write.m4,
the config file for para_write. The writers obtain the sample rate
and the channels count as before via the buffer tree exec mechanism,
but it is now the check_wav node rather than the btr node of the writer
that computes this information from the given option, the wav header
or the builtin default.

The new HANDLE_EXEC macro contains the logic for determining the
source of both the sample rate and the channels count.

Cosmetics: Rename samplerate to sample_rate.

A subsequent patch will introduce sample_format which looks much nicer
than sampleformat. So let's use the underscored variant throughout.

filter.h: Add some missing documentation.

new codename, reset version to git

the paraslash-0.4.3 release tarball

paraslash 0.4.3

Remove some unused error codes.

audiod: Set the audio format restart barrier also when closing the receiver.

When the current audio file changes, it may happen that para_audiod's receiver
detects the EOF condition before the status has been updated to reflect the file
change. In this case, para_audiod might restart the old receiver even if a
different audio format is about to be streamed next.

This patch adds a per audio format 200ms delay which starts at receiver close time.
During this time interval the receiver for this audio format will not be started again.

gui: Replace also \r and \f by spaces.

id3 comments might contain these characters which can mess up the curses output.

oggdec: Introduce a small delay on stream start.

This patch avoids buffer underruns when using the http receiver.

Suppress gcc warning when compiling cmdline files.

Use -Wno-unused-function when compiling *.cmdline.o files
to get rid of the annoying warning

cmdline/mp3dec_filter.cmdline.c:174:1: warning: 'free_string_field' defined but not used

sched: Fix SCHED_DEBUG.

Oops, brown paper bag bug.

NEWS update

Merge branch 't/udp_lookup'

Merge branch 't/sched_debug'

Merge branch 't/decoder_latency'

oss_write: Add missing btr_merge().

Without this patch, the oss writer could detect an EOF condition
even if more data is available.

NEWS update.

Merge branch 't/dccp_fec'

web: Mention the new What's cooking page.

NEWS: Remove header.

The "NEWS" header is now automatically generated by the scripts that
run grutatxt on the NEWS file and insert the "What's cooking" link.

Makefile: Remove oggdec_filter from $all_ggos.

This should have been removed already in the previous patch. With
oggdec_filter still present in $all_ggos, the "tarball" target
can not be made.

fec: make max_slice_size optional

The default max_slice_size for FEC is the MTU. This patch changes the parser
to make the specification of the max_slice_size optional (for cases using a
slice size less than the MTU).

Other changes:
 * added udp sender help documentation;
 * simplified parse_fec_url() (no additional strlen() needed).

sender: miscellaneous cleanups

This collects various minor syntactical changes into a single patch:
 * replace indirection 'ut->sc->xxx' by 'sc->xxx' where possible;
 * more elegant way of duplicating sc->name string;
 * udp_delete_target() now takes sender_client as argument;
 * added IPv4-address:port example for udp_help();
 * revised the definition of E_ADDRESS_LOOKUP (it means what it says)
   and replaced two inappropriate uses by assert(): in each case this
   error value was used to point to an unsupported adress family. But
   since the only supported network protocol is IP, if the case happens,
   it means a bug and should be marked as such.
--
 error.h       |    2 -
 para_audioc   |binary
 error.h       |    2 -
 send_common.c |    2 -
 udp_recv.c    |    4 ---
 udp_send.c    |   64 +++++++++++++++++++++++++++++-----------------------------
 4 files changed, 35 insertions(+), 37 deletions(-)

udp: refuse to add the same target twice

Based on the preceding patches, this turns the UDP targets list into a set.

udp: transition to use sender_client 'name' field

This replaces all occurrences of ut->host/ut->port in the UDP sender with a
'canonical' socket name contained in the embedded sender_client struct.

This field is filled in as soon as the target is added and persists across
shutting down / restarting it.

The host/port fields are now obsolete, thus removed.

udp: integrate resolve hook

This integrates the new resolve hook into the UDP sender; exploiting the
invariant that the 'port' of sender_command_data structure is now always set.

It further reuses the new resolve_target() function for the pre-configured
sender targets. This is necessary to unify the syntax (otherwise the
server.conf would have to be limited to IP-addresses only), and allows to
use hostnames in the server configuration file.

The worst case that can here be anticipated is that unresolvable targets are
specified in server.conf. In this case the server hangs for circa 20 seconds
per unresolvable target, and then concludes with error messages such as:

 (8355) init_vss_task: initializing udp sender
 ...
 (8355) udp_add_target: adding to target list (10.0.0.2:8000)
 (8355) makesock: can not resolve UDP address funzt.net#8000: Name or service not known.
 (8355) udp_init_target_list: not adding requested target 'funzt.net'
 (8355) makesock: can not resolve UDP address funzt.also.net#8000: Name or service not known.
 (8355) udp_init_target_list: not adding requested target 'funzt.also.net'
 (8355) udp_send_init: udp sender init complete

sender: add a hook to resolve target names

This adds a function pointer to interpret and resolve a given URL string in
a target-specific manner, filling in the target's defaults if omitted.

The hook is used for the add/delete commands, currently implemented for UDP.

net: host/port string convention

This updates the implementation of host_and_port() in such a way that its
output can again be used as input of parse_url():

 * the separator for host and port is now ':' instead of '#';
 * port numbers (services) are now always represented as numbers
   (reverting an earlier change);
 * IPv6 addresses are enclosed in square brackets.

This convention makes it easier to copy&paste output from paraslash commands
(including scripting), and to store target information in a format that is
easy to resolve/reuse at a later stage.

Remove oggdec_filter.ggo.

The two options are no longer used.

Make new dccp FEC parameters optional.

Defaults should do for most scenarios.

Reduce decoder latency.

If large/many FEC slices are used, the decoder gets large amounts of
data in one chunk. Currently it decodes as much as it can which may
take several 100 milliseconds on slow machines -- enough to cause
buffer underruns for the alsa writer.

This patch teaches the decoders to convert only a small amount of data
in one go in order to give the other buffer tree nodes a chance to run.

dccp_send: Add command line options for FEC parameters.

ATM, these are hardcoded as MPS/3/4. This patch allows to impose
an upper bound on the slice size and to change the number of (data)
slices of a FEC group.

sched: Add debug mode.

This adds the compile-time switch SCHED_DEBUG to activate debug
mode for the scheduler. If activated, it measures the time spent in
each post_select() function and prints warning messages if this time
interval is too large.

This patch has no effect if SCHED_DEBUG is not set.

Print a log message if the sender command fails.

Currently there is no infrastructure for passing down a value from vss,
which runs in parent context, to the child process. In particular,
we can not pass the return value of the sender subcommand handlers
to com_sender() to propagate it to the client.

However, we may easily write a log message that explains the cause
of the error, which is not optimal, but better than nothing.

Thanks to Gerrit Renker who pointed out this flaw.

udp_send: add a time window for errors

This implements a grace period during which ICMP Destination Unreachable /
Port Unreachable are ignored from the peer, with the purpose of catching
 * synchronisation problems (e.g., receiver started after sender);
 * unforeseen events (e.g. delays, reboot, reconfiguration).

To avoid receiving persistent errors from unicast UDP clients, two time
windows are used:
 (a) The 'error-allowed' period t_A
     This time window starts when the first ECONNREFUSED error is seen
     and ends after t_A seconds. The value of t_A is a guess which should
     cover the expected time needed to sort any receiver problems out.
 (b) The 'error-free' period t_B
     During the t_B seconds following the interval t_A, no further
     connection errors are accepted; if an ECONNREFUSED is seen it
     will cause the target to be evicted from the list.

This windowing process restarts itself, i.e. the first error seen after
t_A+t_B will reset the counters.

The following examples illustrate the algorithm, where 'x' indicates
receipt of an ICMP error message.

 1) Some errors received during initial receiver setup

    |-x-x-x-x-x-x-x--|------------|------....
    |
    t_0              t_0 + t_A    t_0+t_A+t_B

    Since no errors are received after t_0 + t_A, no action will be taken.

 2) Persistent errors

    |-x-x-x-x-x-x-x-x|-x-x-x-x-x-x|
    |
    t_0              t_0 + t_A    t_0+t_A+t_B

    The first error received after t_0+t_A evicts the target.

 3) Recurring short errors

    |-x-x-x-x-x-x-x--|-//--|--------//---|-x-x-x-x-x-x-x--|------------|---...
    |
    t_0                    t_0+t_A+t_B   t_1              t_1+t_A      t_1+t_A+t_B

    Here the counter is reset at the first error after t_1. Since no more errors
    were seen after t_1+t_A, streaming continues.

For simplicity, the implementation uses t_A = t_B = 30 seconds.

The behaviour with an unavailable receiver is now:
May 24 18:08:16 (0) (2702) vss_send: sending 123:0 (548 bytes)
May 24 18:08:18 (0) (2702) vss_send: sending 132:2 (548 bytes)
May 24 18:08:18 (2) (2702) udp_check_socket_state: Evicting 10.0.0.2#8000 after 31 seconds of connection errors.

May 24 19:34:55 (0) (2702) vss_send: sending 5:14 (1232 bytes)
May 24 19:35:10 (0) (2702) vss_send: sending 11:3 (1232 bytes)
May 24 19:35:10 (2) (2702) udp_check_socket_state: Evicting 3ffe::2#8000 after 31 seconds of connection errors.

udp: initialize common structure only once

When temporarily closing the UDP stream (e.g. due to 'next' or 'ff'
command), the UDP file descriptor need not be closed.  Hence this
patch moves its initialization into the add_target() function.

The patch also factors global variables out of mcast_sender_setup() function.

udp_send: Do not send the current chunk if queue is not empty.

In this case we have enqueued other data _and_ the current chunk already.

Move send_chunk() from send_common.c to http_send.c.

Due to the previous changes, this function is no longer a generic function
as it is only used by the http sender. So move it to http_send.c and make it static,
along with the queue_chunk_or_shutdown() helper which is only called from
send_chunk().

cleanup: remove redundant 'max length' argument

This removes the redundant 'max_size_bytes' argument of
 * write_nonblocking(),
 * send_queued_chunks(), and
 * send_chunk(),
since it was set to 0 in all cases.

udp_send: send data in MMS-sized chunks

This determines the Maximum Message Size for the UDPv4/v6 layer; using
the earlier functions. The outcome is used to set the FEC slice size,
initialisation of the UDP client has also been moved to the init_fec()
function.

dccp_send: send data in MPS-sized chunks

As mandated by RFC 4340, 14., DCCP maintains an internal variable called
'Maximum Packet Size', which can be queried via the DCCP_SOCKOPT_GET_CUR_MPS
socket option. This option has been available since 2007-10-04 (v2.6.23)
and is documented in Documentation/networking/dccp.txt.

The Maximum Packet Size takes into account the path MTU, size of headers and
the estimated overhead for DCCP options. The following table shows various
values that were determined experimentally between two hosts:

     +----------+------------+--------------+--------------------+
     | Medium   | IP version | MTU in bytes | Resulting DCCP MPS |
     +----------+------------+--------------+--------------------+
     | Ethernet |    IPv4    |     1500     |     1424 bytes     |
     | Ethernet |    IPv6    |     1500     |     1404 bytes     |
     +----------+------------+--------------+--------------------+
     | WiFi     |    IPv4    |      576     |      500 bytes     |
     | WiFi     |    IPv4    |     1280     |     1204 bytes     |
     | WiFi     |    IPv4    |     1500     |     1424 bytes     |
     | WiFi (a) |    IPv4    |     2048     |     1972 bytes     |
     +----------+------------+--------------+--------------------+
     | WiFi     |    IPv6    |      576     |      see (b)       |
     | WiFi     |    IPv6    |     1280     |     1184 bytes     |
     | WiFi     |    IPv6    |     1500     |     1404 bytes     |
     | WiFi (a) |    IPv6    |     2048     |     1952 bytes     |
     +----------+------------+--------------+--------------------+

Notes:
 (a) WiFi normally uses Ethernet MTU of 1500 bytes, but the medium
     supports a much larger MTU (Fragmentation threshold) of up to
     about 2300 bytes (system used 802.11g).
 (b) 576 byte MTU not tested for IPv6 since IPv6 mandates a minimum
     MTU of 1280 bytes, as per RFC 2460 section 5 (also RFC 5405, 3.2).

The patch implements the dccp init_fec() function based on the DCCP MPS.

net: generic code to query the maximum message size

This adds a fallback routine to determine the address-family specific maximum
message size (MMS). This value is an over-estimation of the maximum payload
size that the network layer can take, i.e. it returns the maximum size for
transport-layer header and transport-layer payload.

sender: clean up old FEC API

After the preceding two patches integrated the new function pointers, this
patch removes the now obsolete open() and send_fec() pointers which are no
longer referenced anywhere. It also reorders send.h to get rid of forward
declarations.

udp: integrate new fec interaction

This patch implements the new UDP-FEC interface in two steps:
 (1) updating the UDP sender analogously to the previous (DCCP sender) patch;
 (2) unifying the struct udp_target by factoring out the fields it has in
     common with 'struct sender_client'.

The open() function is deferred to a subsequent patch. The user can override
the MPS value by supplying a max_slice_bytes value not larger than the MPS.