Commit some cleanups to the format type code.
[asterisk/asterisk.git] / main / translate.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief Translate via the use of pseudo channels
22  *
23  * \author Mark Spencer <markster@digium.com> 
24  */
25
26 #include "asterisk.h"
27
28 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
29
30 #include <sys/types.h>
31 #include <sys/socket.h>
32 #include <sys/time.h>
33 #include <sys/resource.h>
34 #include <unistd.h>
35 #include <stdlib.h>
36 #include <string.h>
37 #include <stdio.h>
38
39 #include "asterisk/lock.h"
40 #include "asterisk/channel.h"
41 #include "asterisk/logger.h"
42 #include "asterisk/translate.h"
43 #include "asterisk/module.h"
44 #include "asterisk/options.h"
45 #include "asterisk/frame.h"
46 #include "asterisk/sched.h"
47 #include "asterisk/cli.h"
48 #include "asterisk/term.h"
49
50 #define MAX_RECALC 1000 /* max sample recalc */
51
52 /*! \brief the list of translators */
53 static AST_RWLIST_HEAD_STATIC(translators, ast_translator);
54
55 struct translator_path {
56         struct ast_translator *step;    /*!< Next step translator */
57         unsigned int cost;              /*!< Complete cost to destination */
58         unsigned int multistep;         /*!< Multiple conversions required for this translation */
59 };
60
61 /*! \brief a matrix that, for any pair of supported formats,
62  * indicates the total cost of translation and the first step.
63  * The full path can be reconstricted iterating on the matrix
64  * until step->dstfmt == desired_format.
65  *
66  * Array indexes are 'src' and 'dest', in that order.
67  *
68  * Note: the lock in the 'translators' list is also used to protect
69  * this structure.
70  */
71 static struct translator_path tr_matrix[MAX_FORMAT][MAX_FORMAT];
72
73 /*! \todo
74  * TODO: sample frames for each supported input format.
75  * We build this on the fly, by taking an SLIN frame and using
76  * the existing converter to play with it.
77  */
78
79 /*! \brief returns the index of the lowest bit set */
80 static force_inline int powerof(unsigned int d)
81 {
82         int x = ffs(d);
83
84         if (x)
85                 return x - 1;
86
87         ast_log(LOG_WARNING, "No bits set? %d\n", d);
88
89         return -1;
90 }
91
92 /*
93  * wrappers around the translator routines.
94  */
95
96 /*!
97  * \brief Allocate the descriptor, required outbuf space,
98  * and possibly also plc and desc.
99  */
100 static void *newpvt(struct ast_translator *t)
101 {
102         struct ast_trans_pvt *pvt;
103         int len;
104         int useplc = t->plc_samples > 0 && t->useplc;   /* cache, because it can change on the fly */
105         char *ofs;
106
107         /*
108          * compute the required size adding private descriptor,
109          * plc, buffer, AST_FRIENDLY_OFFSET.
110          */
111         len = sizeof(*pvt) + t->desc_size;
112         if (useplc)
113                 len += sizeof(plc_state_t);
114         if (t->buf_size)
115                 len += AST_FRIENDLY_OFFSET + t->buf_size;
116         pvt = ast_calloc(1, len);
117         if (!pvt)
118                 return NULL;
119         pvt->t = t;
120         ofs = (char *)(pvt + 1);        /* pointer to data space */
121         if (t->desc_size) {             /* first comes the descriptor */
122                 pvt->pvt = ofs;
123                 ofs += t->desc_size;
124         }
125         if (useplc) {                   /* then plc state */
126                 pvt->plc = (plc_state_t *)ofs;
127                 ofs += sizeof(plc_state_t);
128         }
129         if (t->buf_size)                /* finally buffer and header */
130                 pvt->outbuf = ofs + AST_FRIENDLY_OFFSET;
131         /* call local init routine, if present */
132         if (t->newpvt && t->newpvt(pvt)) {
133                 ast_free(pvt);
134                 return NULL;
135         }
136         ast_module_ref(t->module);
137         return pvt;
138 }
139
140 static void destroy(struct ast_trans_pvt *pvt)
141 {
142         struct ast_translator *t = pvt->t;
143
144         if (t->destroy)
145                 t->destroy(pvt);
146         ast_free(pvt);
147         ast_module_unref(t->module);
148 }
149
150 /*! \brief framein wrapper, deals with plc and bound checks.  */
151 static int framein(struct ast_trans_pvt *pvt, struct ast_frame *f)
152 {
153         int16_t *dst = (int16_t *)pvt->outbuf;
154         int ret;
155         int samples = pvt->samples;     /* initial value */
156         
157         /* Copy the last in jb timing info to the pvt */
158         pvt->f.has_timing_info = f->has_timing_info;
159         pvt->f.ts = f->ts;
160         pvt->f.len = f->len;
161         pvt->f.seqno = f->seqno;
162
163         if (f->samples == 0) {
164                 ast_log(LOG_WARNING, "no samples for %s\n", pvt->t->name);
165         }
166         if (pvt->t->buffer_samples) {   /* do not pass empty frames to callback */
167                 if (f->datalen == 0) { /* perform PLC with nominal framesize of 20ms/160 samples */
168                         if (pvt->plc) {
169                                 int l = pvt->t->plc_samples;
170                                 if (pvt->samples + l > pvt->t->buffer_samples) {
171                                         ast_log(LOG_WARNING, "Out of buffer space\n");
172                                         return -1;
173                                 }
174                                 l = plc_fillin(pvt->plc, dst + pvt->samples, l);
175                                 pvt->samples += l;
176                                 pvt->datalen = pvt->samples * 2;        /* SLIN has 2bytes for 1sample */
177                         }
178                         /* We don't want generic PLC. If the codec has native PLC, then do that */
179                         if (!pvt->t->native_plc)
180                                 return 0;
181                 }
182                 if (pvt->samples + f->samples > pvt->t->buffer_samples) {
183                         ast_log(LOG_WARNING, "Out of buffer space\n");
184                         return -1;
185                 }
186         }
187         /* we require a framein routine, wouldn't know how to do
188          * it otherwise.
189          */
190         ret = pvt->t->framein(pvt, f);
191         /* possibly store data for plc */
192         if (!ret && pvt->plc) {
193                 int l = pvt->t->plc_samples;
194                 if (pvt->samples < l)
195                         l = pvt->samples;
196                 plc_rx(pvt->plc, dst + pvt->samples - l, l);
197         }
198         /* diagnostic ... */
199         if (pvt->samples == samples)
200                 ast_log(LOG_WARNING, "%s did not update samples %d\n",
201                         pvt->t->name, pvt->samples);
202         return ret;
203 }
204
205 /*! \brief generic frameout routine.
206  * If samples and datalen are 0, take whatever is in pvt
207  * and reset them, otherwise take the values in the caller and
208  * leave alone the pvt values.
209  */
210 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
211         int datalen, int samples)
212 {
213         struct ast_frame *f = &pvt->f;
214
215         if (samples)
216                 f->samples = samples;
217         else {
218                 if (pvt->samples == 0)
219                         return NULL;
220                 f->samples = pvt->samples;
221                 pvt->samples = 0;
222         }
223         if (datalen)
224                 f->datalen = datalen;
225         else {
226                 f->datalen = pvt->datalen;
227                 pvt->datalen = 0;
228         }
229
230         f->frametype = AST_FRAME_VOICE;
231         f->subclass = 1 << (pvt->t->dstfmt);
232         f->mallocd = 0;
233         f->offset = AST_FRIENDLY_OFFSET;
234         f->src = pvt->t->name;
235         f->data = pvt->outbuf;
236         return f;
237 }
238
239 static struct ast_frame *default_frameout(struct ast_trans_pvt *pvt)
240 {
241         return ast_trans_frameout(pvt, 0, 0);
242 }
243
244 /* end of callback wrappers and helpers */
245
246 void ast_translator_free_path(struct ast_trans_pvt *p)
247 {
248         struct ast_trans_pvt *pn = p;
249         while ( (p = pn) ) {
250                 pn = p->next;
251                 destroy(p);
252         }
253 }
254
255 /*! \brief Build a chain of translators based upon the given source and dest formats */
256 struct ast_trans_pvt *ast_translator_build_path(int dest, int source)
257 {
258         struct ast_trans_pvt *head = NULL, *tail = NULL;
259         
260         source = powerof(source);
261         dest = powerof(dest);
262         
263         AST_RWLIST_RDLOCK(&translators);
264
265         while (source != dest) {
266                 struct ast_trans_pvt *cur;
267                 struct ast_translator *t = tr_matrix[source][dest].step;
268                 if (!t) {
269                         ast_log(LOG_WARNING, "No translator path from %s to %s\n", 
270                                 ast_getformatname(source), ast_getformatname(dest));
271                         AST_RWLIST_UNLOCK(&translators);
272                         return NULL;
273                 }
274                 if (!(cur = newpvt(t))) {
275                         ast_log(LOG_WARNING, "Failed to build translator step from %d to %d\n", source, dest);
276                         if (head)
277                                 ast_translator_free_path(head); 
278                         AST_RWLIST_UNLOCK(&translators);
279                         return NULL;
280                 }
281                 if (!head)
282                         head = cur;
283                 else
284                         tail->next = cur;
285                 tail = cur;
286                 cur->nextin = cur->nextout = ast_tv(0, 0);
287                 /* Keep going if this isn't the final destination */
288                 source = cur->t->dstfmt;
289         }
290
291         AST_RWLIST_UNLOCK(&translators);
292         return head;
293 }
294
295 /*! \brief do the actual translation */
296 struct ast_frame *ast_translate(struct ast_trans_pvt *path, struct ast_frame *f, int consume)
297 {
298         struct ast_trans_pvt *p = path;
299         struct ast_frame *out = f;
300         struct timeval delivery;
301         int has_timing_info;
302         long ts;
303         long len;
304         int seqno;
305
306         has_timing_info = f->has_timing_info;
307         ts = f->ts;
308         len = f->len;
309         seqno = f->seqno;
310
311         /* XXX hmmm... check this below */
312         if (!ast_tvzero(f->delivery)) {
313                 if (!ast_tvzero(path->nextin)) {
314                         /* Make sure this is in line with what we were expecting */
315                         if (!ast_tveq(path->nextin, f->delivery)) {
316                                 /* The time has changed between what we expected and this
317                                    most recent time on the new packet.  If we have a
318                                    valid prediction adjust our output time appropriately */
319                                 if (!ast_tvzero(path->nextout)) {
320                                         path->nextout = ast_tvadd(path->nextout,
321                                                                   ast_tvsub(f->delivery, path->nextin));
322                                 }
323                                 path->nextin = f->delivery;
324                         }
325                 } else {
326                         /* This is our first pass.  Make sure the timing looks good */
327                         path->nextin = f->delivery;
328                         path->nextout = f->delivery;
329                 }
330                 /* Predict next incoming sample */
331                 path->nextin = ast_tvadd(path->nextin, ast_samp2tv(f->samples, 8000));
332         }
333         delivery = f->delivery;
334         for ( ; out && p ; p = p->next) {
335                 framein(p, out);
336                 out = p->t->frameout(p);
337         }
338         if (consume)
339                 ast_frfree(f);
340         if (out == NULL)
341                 return NULL;
342         /* we have a frame, play with times */
343         if (!ast_tvzero(delivery)) {
344                 /* Regenerate prediction after a discontinuity */
345                 if (ast_tvzero(path->nextout))
346                         path->nextout = ast_tvnow();
347
348                 /* Use next predicted outgoing timestamp */
349                 out->delivery = path->nextout;
350                 
351                 /* Predict next outgoing timestamp from samples in this
352                    frame. */
353                 path->nextout = ast_tvadd(path->nextout, ast_samp2tv( out->samples, 8000));
354         } else {
355                 out->delivery = ast_tv(0, 0);
356                 out->has_timing_info = has_timing_info;
357                 if (has_timing_info) {
358                         out->ts = ts;
359                         out->len = len;
360                         out->seqno = seqno;
361                 }
362         }
363         /* Invalidate prediction if we're entering a silence period */
364         if (out->frametype == AST_FRAME_CNG)
365                 path->nextout = ast_tv(0, 0);
366         return out;
367 }
368
369 /*! \brief compute the cost of a single translation step */
370 static void calc_cost(struct ast_translator *t, int seconds)
371 {
372         int sofar=0;
373         struct ast_trans_pvt *pvt;
374         struct rusage start;
375         struct rusage end;
376         int cost;
377
378         if (!seconds)
379                 seconds = 1;
380         
381         /* If they don't make samples, give them a terrible score */
382         if (!t->sample) {
383                 ast_log(LOG_WARNING, "Translator '%s' does not produce sample frames.\n", t->name);
384                 t->cost = 999999;
385                 return;
386         }
387         pvt = newpvt(t);
388         if (!pvt) {
389                 ast_log(LOG_WARNING, "Translator '%s' appears to be broken and will probably fail.\n", t->name);
390                 t->cost = 999999;
391                 return;
392         }
393         getrusage(RUSAGE_SELF, &start);
394         /* Call the encoder until we've processed the required number of samples */
395         while (sofar < seconds * 8000) {
396                 struct ast_frame *f = t->sample();
397                 if (!f) {
398                         ast_log(LOG_WARNING, "Translator '%s' failed to produce a sample frame.\n", t->name);
399                         destroy(pvt);
400                         t->cost = 999999;
401                         return;
402                 }
403                 framein(pvt, f);
404                 ast_frfree(f);
405                 while ((f = t->frameout(pvt))) {
406                         sofar += f->samples;
407                         ast_frfree(f);
408                 }
409         }
410         getrusage(RUSAGE_SELF, &end);
411         cost = ((end.ru_utime.tv_sec - start.ru_utime.tv_sec)*1000000) + end.ru_utime.tv_usec - start.ru_utime.tv_usec;
412         cost += ((end.ru_stime.tv_sec - start.ru_stime.tv_sec)*1000000) + end.ru_stime.tv_usec - start.ru_stime.tv_usec;
413         destroy(pvt);
414         t->cost = cost / seconds;
415         if (!t->cost)
416                 t->cost = 1;
417 }
418
419 /*!
420  * \brief rebuild a translation matrix.
421  * \note This function expects the list of translators to be locked
422 */
423 static void rebuild_matrix(int samples)
424 {
425         struct ast_translator *t;
426         int x;      /* source format index */
427         int y;      /* intermediate format index */
428         int z;      /* destination format index */
429
430         ast_debug(1, "Resetting translation matrix\n");
431
432         bzero(tr_matrix, sizeof(tr_matrix));
433
434         /* first, compute all direct costs */
435         AST_RWLIST_TRAVERSE(&translators, t, list) {
436                 if (!t->active)
437                         continue;
438
439                 x = t->srcfmt;
440                 z = t->dstfmt;
441
442                 if (samples)
443                         calc_cost(t, samples);
444           
445                 if (!tr_matrix[x][z].step || t->cost < tr_matrix[x][z].cost) {
446                         tr_matrix[x][z].step = t;
447                         tr_matrix[x][z].cost = t->cost;
448                 }
449         }
450
451         /*
452          * For each triple x, y, z of distinct formats, check if there is
453          * a path from x to z through y which is cheaper than what is
454          * currently known, and in case, update the matrix.
455          * Repeat until the matrix is stable.
456          */
457         for (;;) {
458                 int changed = 0;
459                 for (x = 0; x < MAX_FORMAT; x++) {      /* source format */
460                         for (y=0; y < MAX_FORMAT; y++) {    /* intermediate format */
461                                 if (x == y)                     /* skip ourselves */
462                                         continue;
463
464                                 for (z=0; z<MAX_FORMAT; z++) {  /* dst format */
465                                         int newcost;
466
467                                         if (z == x || z == y)       /* skip null conversions */
468                                                 continue;
469                                         if (!tr_matrix[x][y].step)  /* no path from x to y */
470                                                 continue;
471                                         if (!tr_matrix[y][z].step)  /* no path from y to z */
472                                                 continue;
473                                         newcost = tr_matrix[x][y].cost + tr_matrix[y][z].cost;
474                                         if (tr_matrix[x][z].step && newcost >= tr_matrix[x][z].cost)
475                                                 continue;               /* x->y->z is more expensive than
476                                                                          * the existing path */
477                                         /* ok, we can get from x to z via y with a cost that
478                                            is the sum of the transition from x to y and
479                                            from y to z */
480                                                  
481                                         tr_matrix[x][z].step = tr_matrix[x][y].step;
482                                         tr_matrix[x][z].cost = newcost;
483                                         tr_matrix[x][z].multistep = 1;
484                                         ast_debug(3, "Discovered %d cost path from %s to %s, via %d\n", tr_matrix[x][z].cost, ast_getformatname(x), ast_getformatname(z), y);
485                                         changed++;
486                                 }
487                         }
488                 }
489                 if (!changed)
490                         break;
491         }
492 }
493
494 static char *handle_cli_core_show_translation(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
495 {
496 #define SHOW_TRANS 13
497         int x, y, z;
498         int curlen = 0, longest = 0;
499
500         switch (cmd) {
501         case CLI_INIT:
502                 e->command = "core show translation [recalc]";
503                 e->usage =
504                         "Usage: core show translation [recalc] [<recalc seconds>]\n"
505                         "       Displays known codec translators and the cost associated\n"
506                         "       with each conversion.  If the argument 'recalc' is supplied along\n"
507                         "       with optional number of seconds to test a new test will be performed\n"
508                         "       as the chart is being displayed.\n";
509                 return NULL;
510         case CLI_GENERATE:
511                 return NULL;
512         }
513
514         if (a->argc > 5)
515                 return CLI_SHOWUSAGE;
516         
517         if (a->argv[3] && !strcasecmp(a->argv[3], "recalc")) {
518                 z = a->argv[4] ? atoi(a->argv[4]) : 1;
519
520                 if (z <= 0) {
521                         ast_cli(a->fd, "         Recalc must be greater than 0.  Defaulting to 1.\n");
522                         z = 1;
523                 }
524
525                 if (z > MAX_RECALC) {
526                         ast_cli(a->fd, "         Maximum limit of recalc exceeded by %d, truncating value to %d\n", z - MAX_RECALC, MAX_RECALC);
527                         z = MAX_RECALC;
528                 }
529                 ast_cli(a->fd, "         Recalculating Codec Translation (number of sample seconds: %d)\n\n", z);
530                 AST_RWLIST_WRLOCK(&translators);
531                 rebuild_matrix(z);
532                 AST_RWLIST_UNLOCK(&translators);
533         }
534
535         AST_RWLIST_RDLOCK(&translators);
536
537         ast_cli(a->fd, "         Translation times between formats (in microseconds) for one second of data\n");
538         ast_cli(a->fd, "          Source Format (Rows) Destination Format (Columns)\n\n");
539         /* Get the length of the longest (usable?) codec name, so we know how wide the left side should be */
540         for (x = 0; x < SHOW_TRANS; x++) {
541                 curlen = strlen(ast_getformatname(1 << (x + 1)));
542                 if (curlen > longest)
543                         longest = curlen;
544         }
545         for (x = -1; x < SHOW_TRANS; x++) {
546                 struct ast_str *out = ast_str_alloca(120);
547                 
548                 ast_str_set(&out, -1, " ");
549                 for (y = -1; y < SHOW_TRANS; y++) {
550                         curlen = strlen(ast_getformatname(1 << (y)));
551                         if (curlen < 5)
552                                 curlen = 5;
553                         if (x >= 0 && y >= 0 && tr_matrix[x][y].step) {
554                                 /* XXX 99999 is a little hackish
555                                    We don't want this number being larger than the shortest (or current) codec
556                                    For now, that is "gsm" */
557                                 ast_str_append(&out, -1, "%*d", curlen + 1, tr_matrix[x][y].cost > 99999 ? 0 : tr_matrix[x][y].cost);
558                         } else if (x == -1 && y >= 0) {
559                                 /* Top row - use a dynamic size */
560                                 ast_str_append(&out, -1, "%*s", curlen + 1, ast_getformatname(1 << (x + y + 1)) );
561                         } else if (y == -1 && x >= 0) {
562                                 /* Left column - use a static size. */
563                                 ast_str_append(&out, -1, "%*s", longest, ast_getformatname(1 << (x + y + 1)) );
564                         } else if (x >= 0 && y >= 0) {
565                                 ast_str_append(&out, -1, "%*s", curlen + 1, "-");
566                         } else {
567                                 ast_str_append(&out, -1, "%*s", longest, "");
568                         }
569                 }
570                 ast_str_append(&out, -1, "\n");
571                 ast_cli(a->fd, out->str);                       
572         }
573         AST_RWLIST_UNLOCK(&translators);
574         return CLI_SUCCESS;
575 }
576
577 static struct ast_cli_entry cli_translate[] = {
578         AST_CLI_DEFINE(handle_cli_core_show_translation, "Display translation matrix")
579 };
580
581 /*! \brief register codec translator */
582 int __ast_register_translator(struct ast_translator *t, struct ast_module *mod)
583 {
584         static int added_cli = 0;
585         struct ast_translator *u;
586         char tmp[80];
587
588         if (!mod) {
589                 ast_log(LOG_WARNING, "Missing module pointer, you need to supply one\n");
590                 return -1;
591         }
592
593         if (!t->buf_size) {
594                 ast_log(LOG_WARNING, "empty buf size, you need to supply one\n");
595                 return -1;
596         }
597
598         t->module = mod;
599
600         t->srcfmt = powerof(t->srcfmt);
601         t->dstfmt = powerof(t->dstfmt);
602         t->active = 1;
603
604         if (t->plc_samples) {
605                 if (t->buffer_samples < t->plc_samples) {
606                         ast_log(LOG_WARNING, "plc_samples %d buffer_samples %d\n",
607                                 t->plc_samples, t->buffer_samples);
608                         return -1;
609                 }
610                 if (t->dstfmt != powerof(AST_FORMAT_SLINEAR))
611                         ast_log(LOG_WARNING, "plc_samples %d format %x\n",
612                                 t->plc_samples, t->dstfmt);
613         }
614         if (t->srcfmt >= MAX_FORMAT) {
615                 ast_log(LOG_WARNING, "Source format %s is larger than MAX_FORMAT\n", ast_getformatname(t->srcfmt));
616                 return -1;
617         }
618
619         if (t->dstfmt >= MAX_FORMAT) {
620                 ast_log(LOG_WARNING, "Destination format %s is larger than MAX_FORMAT\n", ast_getformatname(t->dstfmt));
621                 return -1;
622         }
623
624         if (t->buf_size) {
625                /*
626                 * Align buf_size properly, rounding up to the machine-specific
627                 * alignment for pointers.
628                 */
629                 struct _test_align { void *a, *b; } p;
630                 int align = (char *)&p.b - (char *)&p.a;
631
632                 t->buf_size = ((t->buf_size + align - 1) / align) * align;
633         }
634
635         if (t->frameout == NULL)
636                 t->frameout = default_frameout;
637   
638         calc_cost(t, 1);
639
640         ast_verb(2, "Registered translator '%s' from format %s to %s, cost %d\n",
641                             term_color(tmp, t->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(tmp)),
642                             ast_getformatname(1 << t->srcfmt), ast_getformatname(1 << t->dstfmt), t->cost);
643
644         if (!added_cli) {
645                 ast_cli_register_multiple(cli_translate, sizeof(cli_translate) / sizeof(struct ast_cli_entry));
646                 added_cli++;
647         }
648
649         AST_RWLIST_WRLOCK(&translators);
650
651         /* find any existing translators that provide this same srcfmt/dstfmt,
652            and put this one in order based on cost */
653         AST_RWLIST_TRAVERSE_SAFE_BEGIN(&translators, u, list) {
654                 if ((u->srcfmt == t->srcfmt) &&
655                     (u->dstfmt == t->dstfmt) &&
656                     (u->cost > t->cost)) {
657                         AST_RWLIST_INSERT_BEFORE_CURRENT(&translators, t, list);
658                         t = NULL;
659                 }
660         }
661         AST_RWLIST_TRAVERSE_SAFE_END;
662
663         /* if no existing translator was found for this format combination,
664            add it to the beginning of the list */
665         if (t)
666                 AST_RWLIST_INSERT_HEAD(&translators, t, list);
667
668         rebuild_matrix(0);
669
670         AST_RWLIST_UNLOCK(&translators);
671
672         return 0;
673 }
674
675 /*! \brief unregister codec translator */
676 int ast_unregister_translator(struct ast_translator *t)
677 {
678         char tmp[80];
679         struct ast_translator *u;
680         int found = 0;
681
682         AST_RWLIST_WRLOCK(&translators);
683         AST_RWLIST_TRAVERSE_SAFE_BEGIN(&translators, u, list) {
684                 if (u == t) {
685                         AST_RWLIST_REMOVE_CURRENT(&translators, list);
686                         ast_verb(2, "Unregistered translator '%s' from format %s to %s\n", term_color(tmp, t->name, COLOR_MAGENTA, COLOR_BLACK, sizeof(tmp)), ast_getformatname(1 << t->srcfmt), ast_getformatname(1 << t->dstfmt));
687                         found = 1;
688                         break;
689                 }
690         }
691         AST_RWLIST_TRAVERSE_SAFE_END;
692
693         if (found)
694                 rebuild_matrix(0);
695
696         AST_RWLIST_UNLOCK(&translators);
697
698         return (u ? 0 : -1);
699 }
700
701 void ast_translator_activate(struct ast_translator *t)
702 {
703         AST_RWLIST_WRLOCK(&translators);
704         t->active = 1;
705         rebuild_matrix(0);
706         AST_RWLIST_UNLOCK(&translators);
707 }
708
709 void ast_translator_deactivate(struct ast_translator *t)
710 {
711         AST_RWLIST_WRLOCK(&translators);
712         t->active = 0;
713         rebuild_matrix(0);
714         AST_RWLIST_UNLOCK(&translators);
715 }
716
717 /*! \brief Calculate our best translator source format, given costs, and a desired destination */
718 int ast_translator_best_choice(int *dst, int *srcs)
719 {
720         int x,y;
721         int best = -1;
722         int bestdst = 0;
723         int cur, cursrc;
724         int besttime = INT_MAX;
725         int beststeps = INT_MAX;
726         int common = (*dst) & (*srcs);  /* are there common formats ? */
727
728         if (common) { /* yes, pick one and return */
729                 for (cur = 1, y = 0; y < MAX_FORMAT; cur <<= 1, y++) {
730                         if (cur & common)       /* guaranteed to find one */
731                                 break;
732                 }
733                 /* We are done, this is a common format to both. */
734                 *srcs = *dst = cur;
735                 return 0;
736         } else {        /* No, we will need to translate */
737                 AST_RWLIST_RDLOCK(&translators);
738                 for (cur = 1, y = 0; y < MAX_FORMAT; cur <<= 1, y++) {
739                         if (! (cur & *dst))
740                                 continue;
741                         for (cursrc = 1, x = 0; x < MAX_FORMAT; cursrc <<= 1, x++) {
742                                 if (!(*srcs & cursrc) || !tr_matrix[x][y].step ||
743                                     tr_matrix[x][y].cost >  besttime)
744                                         continue;       /* not existing or no better */
745                                 if (tr_matrix[x][y].cost < besttime ||
746                                     tr_matrix[x][y].multistep < beststeps) {
747                                         /* better than what we have so far */
748                                         best = cursrc;
749                                         bestdst = cur;
750                                         besttime = tr_matrix[x][y].cost;
751                                         beststeps = tr_matrix[x][y].multistep;
752                                 }
753                         }
754                 }
755                 AST_RWLIST_UNLOCK(&translators);
756                 if (best > -1) {
757                         *srcs = best;
758                         *dst = bestdst;
759                         best = 0;
760                 }
761                 return best;
762         }
763 }
764
765 unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src)
766 {
767         unsigned int res = -1;
768
769         /* convert bitwise format numbers into array indices */
770         src = powerof(src);
771         dest = powerof(dest);
772
773         AST_RWLIST_RDLOCK(&translators);
774
775         if (tr_matrix[src][dest].step)
776                 res = tr_matrix[src][dest].multistep + 1;
777
778         AST_RWLIST_UNLOCK(&translators);
779
780         return res;
781 }
782
783 unsigned int ast_translate_available_formats(unsigned int dest, unsigned int src)
784 {
785         unsigned int res = dest;
786         unsigned int x;
787         unsigned int src_audio = src & AST_FORMAT_AUDIO_MASK;
788         unsigned int src_video = src & AST_FORMAT_VIDEO_MASK;
789
790         /* if we don't have a source format, we just have to try all
791            possible destination formats */
792         if (!src)
793                 return dest;
794
795         /* If we have a source audio format, get its format index */
796         if (src_audio)
797                 src_audio = powerof(src_audio);
798
799         /* If we have a source video format, get its format index */
800         if (src_video)
801                 src_video = powerof(src_video);
802
803         AST_RWLIST_RDLOCK(&translators);
804
805         /* For a given source audio format, traverse the list of
806            known audio formats to determine whether there exists
807            a translation path from the source format to the
808            destination format. */
809         for (x = 1; src_audio && (x & AST_FORMAT_AUDIO_MASK); x <<= 1) {
810                 /* if this is not a desired format, nothing to do */
811                 if (!dest & x)
812                         continue;
813
814                 /* if the source is supplying this format, then
815                    we can leave it in the result */
816                 if (src & x)
817                         continue;
818
819                 /* if we don't have a translation path from the src
820                    to this format, remove it from the result */
821                 if (!tr_matrix[src_audio][powerof(x)].step) {
822                         res &= ~x;
823                         continue;
824                 }
825
826                 /* now check the opposite direction */
827                 if (!tr_matrix[powerof(x)][src_audio].step)
828                         res &= ~x;
829         }
830
831         /* For a given source video format, traverse the list of
832            known video formats to determine whether there exists
833            a translation path from the source format to the
834            destination format. */
835         for (; src_video && (x & AST_FORMAT_VIDEO_MASK); x <<= 1) {
836                 /* if this is not a desired format, nothing to do */
837                 if (!dest & x)
838                         continue;
839
840                 /* if the source is supplying this format, then
841                    we can leave it in the result */
842                 if (src & x)
843                         continue;
844
845                 /* if we don't have a translation path from the src
846                    to this format, remove it from the result */
847                 if (!tr_matrix[src_video][powerof(x)].step) {
848                         res &= ~x;
849                         continue;
850                 }
851
852                 /* now check the opposite direction */
853                 if (!tr_matrix[powerof(x)][src_video].step)
854                         res &= ~x;
855         }
856
857         AST_RWLIST_UNLOCK(&translators);
858
859         return res;
860 }