From d9fc5177f12b313dc82a841d102150617da33c13 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Sat, 2 Aug 2008 04:39:28 +0000 Subject: Convert most of the existing comments in kernel.h to doxygen format git-svn-id: http://svn.asterisk.org/svn/dahdi/linux/trunk@4658 a0bf4364-ded3-4de4-8d8a-66a801d63aff --- include/dahdi/kernel.h | 452 +++++++++++++++++++++++++------------------------ 1 file changed, 229 insertions(+), 223 deletions(-) (limited to 'include') diff --git a/include/dahdi/kernel.h b/include/dahdi/kernel.h index cbfadd0..cae305b 100644 --- a/include/dahdi/kernel.h +++ b/include/dahdi/kernel.h @@ -24,6 +24,11 @@ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ +/*! + * \file + * \brief DAHDI kernel interface definitions + */ + #ifndef _DAHDI_KERNEL_H #define _DAHDI_KERNEL_H @@ -72,7 +77,7 @@ #define DAHDI_IRQ_SHARED_DISABLED SA_SHIRQ | SA_INTERRUPT #endif -/* Default chunk size for conferences and such -- static right now, might make +/*! Default chunk size for conferences and such -- static right now, might make variable sometime. 8 samples = 1 ms = most frequent service interval possible for a USB device */ #define DAHDI_CHUNKSIZE 8 @@ -81,7 +86,7 @@ #define DAHDI_MAX_CHUNKSIZE DAHDI_CHUNKSIZE #define DAHDI_CB_SIZE 2 -#define RING_DEBOUNCE_TIME 2000 /* 2000 ms ring debounce time */ +#define RING_DEBOUNCE_TIME 2000 /*!< 2000 ms ring debounce time */ #include "ecdis.h" @@ -107,7 +112,7 @@ struct dahdi_tone_state { int modulate; }; -/* Conference queue stucture */ +/*! \brief Conference queue structure */ struct confq { u_char buffer[DAHDI_CHUNKSIZE * DAHDI_CB_SIZE]; u_char *buf[DAHDI_CB_SIZE]; @@ -117,7 +122,7 @@ struct confq { struct dahdi_chan { #ifdef CONFIG_DAHDI_NET - /* Must be first */ + /*! \note Must be first */ struct dahdi_hdlc *hdlcnetdev; #endif #ifdef CONFIG_DAHDI_PPP @@ -128,9 +133,10 @@ struct dahdi_chan { struct sk_buff_head ppp_rq; #endif spinlock_t lock; - char name[40]; /* Name */ + char name[40]; /* Specified by DAHDI */ - int channo; /* DAHDI Channel number */ + /*! \brief DAHDI channel number */ + int channo; int chanpos; unsigned long flags; long rxp1; @@ -145,90 +151,90 @@ struct dahdi_chan { int toneflags; sf_detect_state_t rd; - struct dahdi_chan *master; /* Our Master channel (could be us) */ - /* Next slave (if appropriate) */ + struct dahdi_chan *master; /*!< Our Master channel (could be us) */ + /*! \brief Next slave (if appropriate) */ int nextslave; - u_char *writechunk; /* Actual place to write to */ - u_char swritechunk[DAHDI_MAX_CHUNKSIZE]; /* Buffer to be written */ - u_char *readchunk; /* Actual place to read from */ - u_char sreadchunk[DAHDI_MAX_CHUNKSIZE]; /* Preallocated static area */ + u_char *writechunk; /*!< Actual place to write to */ + u_char swritechunk[DAHDI_MAX_CHUNKSIZE]; /*!< Buffer to be written */ + u_char *readchunk; /*!< Actual place to read from */ + u_char sreadchunk[DAHDI_MAX_CHUNKSIZE]; /*!< Preallocated static area */ short *readchunkpreec; - /* Pointer to tx and rx gain tables */ + /*! Pointer to tx and rx gain tables */ u_char *rxgain; u_char *txgain; - /* Whether or not we have allocated gains or are using the default */ + /*! Whether or not we have allocated gains or are using the default */ int gainalloc; /* Specified by driver, readable by DAHDI */ - void *pvt; /* Private channel data */ - struct file *file; /* File structure */ + void *pvt; /*!< Private channel data */ + struct file *file; /*!< File structure */ - struct dahdi_span *span; /* Span we're a member of */ - int sig; /* Signalling */ - int sigcap; /* Capability for signalling */ - __u32 chan_alarms; /* alarms status */ + struct dahdi_span *span; /*!< Span we're a member of */ + int sig; /*!< Signalling */ + int sigcap; /*!< Capability for signalling */ + __u32 chan_alarms; /*!< alarms status */ /* Used only by DAHDI -- NO DRIVER SERVICEABLE PARTS BELOW */ /* Buffer declarations */ - u_char *readbuf[DAHDI_MAX_NUM_BUFS]; /* read buffer */ + u_char *readbuf[DAHDI_MAX_NUM_BUFS]; /*!< read buffer */ int inreadbuf; int outreadbuf; - wait_queue_head_t readbufq; /* read wait queue */ + wait_queue_head_t readbufq; /*!< read wait queue */ - u_char *writebuf[DAHDI_MAX_NUM_BUFS]; /* write buffers */ + u_char *writebuf[DAHDI_MAX_NUM_BUFS]; /*!< write buffers */ int inwritebuf; int outwritebuf; - wait_queue_head_t writebufq; /* write wait queue */ + wait_queue_head_t writebufq; /*!< write wait queue */ - int blocksize; /* Block size */ + int blocksize; /*!< Block size */ - int eventinidx; /* out index in event buf (circular) */ - int eventoutidx; /* in index in event buf (circular) */ - unsigned int eventbuf[DAHDI_MAX_EVENTSIZE]; /* event circ. buffer */ - wait_queue_head_t eventbufq; /* event wait queue */ + int eventinidx; /*!< out index in event buf (circular) */ + int eventoutidx; /*!< in index in event buf (circular) */ + unsigned int eventbuf[DAHDI_MAX_EVENTSIZE]; /*!< event circ. buffer */ + wait_queue_head_t eventbufq; /*!< event wait queue */ - wait_queue_head_t txstateq; /* waiting on the tx state to change */ + wait_queue_head_t txstateq; /*!< waiting on the tx state to change */ - int readn[DAHDI_MAX_NUM_BUFS]; /* # of bytes ready in read buf */ - int readidx[DAHDI_MAX_NUM_BUFS]; /* current read pointer */ - int writen[DAHDI_MAX_NUM_BUFS]; /* # of bytes ready in write buf */ - int writeidx[DAHDI_MAX_NUM_BUFS]; /* current write pointer */ + int readn[DAHDI_MAX_NUM_BUFS]; /*!< # of bytes ready in read buf */ + int readidx[DAHDI_MAX_NUM_BUFS]; /*!< current read pointer */ + int writen[DAHDI_MAX_NUM_BUFS]; /*!< # of bytes ready in write buf */ + int writeidx[DAHDI_MAX_NUM_BUFS]; /*!< current write pointer */ - int numbufs; /* How many buffers in channel */ - int txbufpolicy; /* Buffer policy */ - int rxbufpolicy; /* Buffer policy */ - int txdisable; /* Disable transmitter */ - int rxdisable; /* Disable receiver */ + int numbufs; /*!< How many buffers in channel */ + int txbufpolicy; /*!< Buffer policy */ + int rxbufpolicy; /*!< Buffer policy */ + int txdisable; /*!< Disable transmitter */ + int rxdisable; /*!< Disable receiver */ /* Tone zone stuff */ - struct dahdi_zone *curzone; /* Zone for selecting tones */ - int tonezone; /* Tone zone for this channel */ - struct dahdi_tone *curtone; /* Current tone we're playing (if any) */ - int tonep; /* Current position in tone */ - struct dahdi_tone_state ts; /* Tone state */ + struct dahdi_zone *curzone; /*!< Zone for selecting tones */ + int tonezone; /*!< Tone zone for this channel */ + struct dahdi_tone *curtone; /*!< Current tone we're playing (if any) */ + int tonep; /*!< Current position in tone */ + struct dahdi_tone_state ts; /*!< Tone state */ /* Pulse dial stuff */ - int pdialcount; /* pulse dial count */ + int pdialcount; /*!< pulse dial count */ - /* Ring cadence */ + /*! Ring cadence */ int ringcadence[DAHDI_MAX_CADENCE]; - int firstcadencepos; /* Where to restart ring cadence */ + int firstcadencepos; /*!< Where to restart ring cadence */ /* Digit string dialing stuff */ - int digitmode; /* What kind of tones are we sending? */ + int digitmode; /*!< What kind of tones are we sending? */ char txdialbuf[DAHDI_MAX_DTMF_BUF]; int dialing; int afterdialingtimer; - int cadencepos; /* Where in the cadence we are */ + int cadencepos; /*!< Where in the cadence we are */ /* I/O Mask */ - int iomask; /* I/O Mux signal mask */ - wait_queue_head_t sel; /* thingy for select stuff */ + int iomask; /*! I/O Mux signal mask */ + wait_queue_head_t sel; /*! thingy for select stuff */ /* HDLC state machines */ struct fasthdlc_state txhdlc; @@ -236,10 +242,10 @@ struct dahdi_chan { int infcs; /* Conferencing stuff */ - int confna; /* conference number (alias) */ - int _confn; /* Actual conference number */ - int confmode; /* conference mode */ - int confmute; /* conference mute mode */ + int confna; /*! conference number (alias) */ + int _confn; /*! Actual conference number */ + int confmode; /*! conference mode */ + int confmute; /*! conference mute mode */ /* Incoming and outgoing conference chunk queues for communicating between DAHDI master time and @@ -247,50 +253,50 @@ struct dahdi_chan { struct confq confin; struct confq confout; - short getlin[DAHDI_MAX_CHUNKSIZE]; /* Last transmitted samples */ - unsigned char getraw[DAHDI_MAX_CHUNKSIZE]; /* Last received raw data */ - short getlin_lastchunk[DAHDI_MAX_CHUNKSIZE]; /* Last transmitted samples from last chunk */ - short putlin[DAHDI_MAX_CHUNKSIZE]; /* Last received samples */ - unsigned char putraw[DAHDI_MAX_CHUNKSIZE]; /* Last received raw data */ - short conflast[DAHDI_MAX_CHUNKSIZE]; /* Last conference sample -- base part of channel */ - short conflast1[DAHDI_MAX_CHUNKSIZE]; /* Last conference sample -- pseudo part of channel */ - short conflast2[DAHDI_MAX_CHUNKSIZE]; /* Previous last conference sample -- pseudo part of channel */ + short getlin[DAHDI_MAX_CHUNKSIZE]; /*!< Last transmitted samples */ + unsigned char getraw[DAHDI_MAX_CHUNKSIZE]; /*!< Last received raw data */ + short getlin_lastchunk[DAHDI_MAX_CHUNKSIZE]; /*!< Last transmitted samples from last chunk */ + short putlin[DAHDI_MAX_CHUNKSIZE]; /*!< Last received samples */ + unsigned char putraw[DAHDI_MAX_CHUNKSIZE]; /*!< Last received raw data */ + short conflast[DAHDI_MAX_CHUNKSIZE]; /*!< Last conference sample -- base part of channel */ + short conflast1[DAHDI_MAX_CHUNKSIZE]; /*!< Last conference sample -- pseudo part of channel */ + short conflast2[DAHDI_MAX_CHUNKSIZE]; /*!< Previous last conference sample -- pseudo part of channel */ - /* Is echo cancellation enabled or disabled */ + /*! Is echo cancellation enabled or disabled */ int echocancel; - /* The echo canceler module that should be used to create an + /*! The echo canceler module that should be used to create an instance when this channel needs one */ const struct dahdi_echocan *ec_factory; - /* The echo canceler module that owns the instance currently + /*! The echo canceler module that owns the instance currently on this channel, if one is present */ const struct dahdi_echocan *ec_current; - /* The private state data of the echo canceler instance in use */ + /*! The private state data of the echo canceler instance in use */ struct echo_can_state *ec_state; echo_can_disable_detector_state_t txecdis; echo_can_disable_detector_state_t rxecdis; - int echostate; /* State of echo canceller */ - int echolastupdate; /* Last echo can update pos */ - int echotimer; /* Timer for echo update */ + int echostate; /*!< State of echo canceller */ + int echolastupdate; /*!< Last echo can update pos */ + int echotimer; /*!< Timer for echo update */ /* RBS timings */ - int prewinktime; /* pre-wink time (ms) */ - int preflashtime; /* pre-flash time (ms) */ - int winktime; /* wink time (ms) */ - int flashtime; /* flash time (ms) */ - int starttime; /* start time (ms) */ - int rxwinktime; /* rx wink time (ms) */ - int rxflashtime; /* rx flash time (ms) */ - int debouncetime; /* FXS GS sig debounce time (ms) */ - int pulsebreaktime; /* pulse line open time (ms) */ - int pulsemaketime; /* pulse line closed time (ms) */ - int pulseaftertime; /* pulse time between digits (ms) */ - - /* RING debounce timer */ + int prewinktime; /*!< pre-wink time (ms) */ + int preflashtime; /*!< pre-flash time (ms) */ + int winktime; /*!< wink time (ms) */ + int flashtime; /*!< flash time (ms) */ + int starttime; /*!< start time (ms) */ + int rxwinktime; /*!< rx wink time (ms) */ + int rxflashtime; /*!< rx flash time (ms) */ + int debouncetime; /*!< FXS GS sig debounce time (ms) */ + int pulsebreaktime; /*!< pulse line open time (ms) */ + int pulsemaketime; /*!< pulse line closed time (ms) */ + int pulseaftertime; /*!< pulse time between digits (ms) */ + + /*! RING debounce timer */ int ringdebtimer; - /* RING trailing detector to make sure a RING is really over */ + /*! RING trailing detector to make sure a RING is really over */ int ringtrailer; /* PULSE digit receiver stuff */ @@ -298,7 +304,7 @@ struct dahdi_chan { int pulsetimer; /* RBS timers */ - int itimerset; /* what the itimer was set to last */ + int itimerset; /*!< what the itimer was set to last */ int itimer; int otimer; @@ -314,10 +320,10 @@ struct dahdi_chan { int txhooksig; int kewlonhook; - /* Idle signalling if CAS signalling */ + /*! Idle signalling if CAS signalling */ int idlebits; - int deflaw; /* 1 = mulaw, 2=alaw, 0=undefined */ + int deflaw; /*! 1 = mulaw, 2=alaw, 0=undefined */ short *xlaw; #ifdef OPTIMIZE_CHANMUTE int chanmute; /*!< no need for PCM data */ @@ -351,56 +357,56 @@ struct dahdi_echocan { int dahdi_register_echocan(const struct dahdi_echocan *ec); void dahdi_unregister_echocan(const struct dahdi_echocan *ec); -/* Define the maximum block size */ +/*! Define the maximum block size */ #define DAHDI_MAX_BLOCKSIZE 8192 -/* Define the default network block size */ +/*! Define the default network block size */ #define DAHDI_DEFAULT_MTU_MRU 2048 -#define DAHDI_DEFAULT_WINKTIME 150 /* 150 ms default wink time */ -#define DAHDI_DEFAULT_FLASHTIME 750 /* 750 ms default flash time */ +#define DAHDI_DEFAULT_WINKTIME 150 /*!< 150 ms default wink time */ +#define DAHDI_DEFAULT_FLASHTIME 750 /*!< 750 ms default flash time */ -#define DAHDI_DEFAULT_PREWINKTIME 50 /* 50 ms before wink */ -#define DAHDI_DEFAULT_PREFLASHTIME 50 /* 50 ms before flash */ -#define DAHDI_DEFAULT_STARTTIME 1500 /* 1500 ms of start */ -#define DAHDI_DEFAULT_RINGTIME 2000 /* 2000 ms of ring on (start, FXO) */ +#define DAHDI_DEFAULT_PREWINKTIME 50 /*!< 50 ms before wink */ +#define DAHDI_DEFAULT_PREFLASHTIME 50 /*!< 50 ms before flash */ +#define DAHDI_DEFAULT_STARTTIME 1500 /*!< 1500 ms of start */ +#define DAHDI_DEFAULT_RINGTIME 2000 /*!< 2000 ms of ring on (start, FXO) */ #if 0 -#define DAHDI_DEFAULT_RXWINKTIME 250 /* 250ms longest rx wink */ +#define DAHDI_DEFAULT_RXWINKTIME 250 /*!< 250ms longest rx wink */ #endif -#define DAHDI_DEFAULT_RXWINKTIME 300 /* 300ms longest rx wink (to work with the Atlas) */ -#define DAHDI_DEFAULT_RXFLASHTIME 1250 /* 1250ms longest rx flash */ -#define DAHDI_DEFAULT_DEBOUNCETIME 600 /* 600ms of FXS GS signalling debounce */ -#define DAHDI_DEFAULT_PULSEMAKETIME 50 /* 50 ms of line closed when dial pulsing */ -#define DAHDI_DEFAULT_PULSEBREAKTIME 50 /* 50 ms of line open when dial pulsing */ -#define DAHDI_DEFAULT_PULSEAFTERTIME 750 /* 750ms between dial pulse digits */ +#define DAHDI_DEFAULT_RXWINKTIME 300 /*!< 300ms longest rx wink (to work with the Atlas) */ +#define DAHDI_DEFAULT_RXFLASHTIME 1250 /*!< 1250ms longest rx flash */ +#define DAHDI_DEFAULT_DEBOUNCETIME 600 /*!< 600ms of FXS GS signalling debounce */ +#define DAHDI_DEFAULT_PULSEMAKETIME 50 /*!< 50 ms of line closed when dial pulsing */ +#define DAHDI_DEFAULT_PULSEBREAKTIME 50 /*!< 50 ms of line open when dial pulsing */ +#define DAHDI_DEFAULT_PULSEAFTERTIME 750 /*!< 750ms between dial pulse digits */ -#define DAHDI_MINPULSETIME (15 * 8) /* 15 ms minimum */ +#define DAHDI_MINPULSETIME (15 * 8) /*!< 15 ms minimum */ #ifdef SHORT_FLASH_TIME -#define DAHDI_MAXPULSETIME (80 * 8) /* we need 80 ms, not 200ms, as we have a short flash */ +#define DAHDI_MAXPULSETIME (80 * 8) /*!< we need 80 ms, not 200ms, as we have a short flash */ #else -#define DAHDI_MAXPULSETIME (200 * 8) /* 200 ms maximum */ +#define DAHDI_MAXPULSETIME (200 * 8) /*!< 200 ms maximum */ #endif #define DAHDI_PULSETIMEOUT ((DAHDI_MAXPULSETIME / 8) + 50) -#define DAHDI_RINGTRAILER (50 * 8) /* Don't consider a ring "over" until it's been gone at least this +#define DAHDI_RINGTRAILER (50 * 8) /*!< Don't consider a ring "over" until it's been gone at least this much time */ -#define DAHDI_LOOPCODE_TIME 10000 /* send loop codes for 10 secs */ -#define DAHDI_ALARMSETTLE_TIME 5000 /* allow alarms to settle for 5 secs */ -#define DAHDI_AFTERSTART_TIME 500 /* 500ms after start */ +#define DAHDI_LOOPCODE_TIME 10000 /*!< send loop codes for 10 secs */ +#define DAHDI_ALARMSETTLE_TIME 5000 /*!< allow alarms to settle for 5 secs */ +#define DAHDI_AFTERSTART_TIME 500 /*!< 500ms after start */ -#define DAHDI_RINGOFFTIME 4000 /* Turn off ringer for 4000 ms */ -#define DAHDI_KEWLTIME 500 /* 500ms for kewl pulse */ -#define DAHDI_AFTERKEWLTIME 300 /* 300ms after kewl pulse */ +#define DAHDI_RINGOFFTIME 4000 /*!< Turn off ringer for 4000 ms */ +#define DAHDI_KEWLTIME 500 /*!< 500ms for kewl pulse */ +#define DAHDI_AFTERKEWLTIME 300 /*!< 300ms after kewl pulse */ -#define DAHDI_MAX_PRETRAINING 1000 /* 1000ms max pretraining time */ +#define DAHDI_MAX_PRETRAINING 1000 /*!< 1000ms max pretraining time */ #ifdef FXSFLASH -#define DAHDI_FXSFLASHMINTIME 450 /* min 450ms */ -#define DAHDI_FXSFLASHMAXTIME 550 /* max 550ms */ +#define DAHDI_FXSFLASHMINTIME 450 /*!< min 450ms */ +#define DAHDI_FXSFLASHMAXTIME 550 /*!< max 550ms */ #endif @@ -412,12 +418,12 @@ struct dahdi_chardev { int dahdi_register_chardev(struct dahdi_chardev *dev); int dahdi_unregister_chardev(struct dahdi_chardev *dev); -/* defines for transmit signalling */ +/*! \brief defines for transmit signalling */ typedef enum { - DAHDI_TXSIG_ONHOOK, /* On hook */ - DAHDI_TXSIG_OFFHOOK, /* Off hook */ - DAHDI_TXSIG_START, /* Start / Ring */ - DAHDI_TXSIG_KEWL /* Drop battery if possible */ + DAHDI_TXSIG_ONHOOK, /*!< On hook */ + DAHDI_TXSIG_OFFHOOK, /*!< Off hook */ + DAHDI_TXSIG_START, /*!< Start / Ring */ + DAHDI_TXSIG_KEWL /*!< Drop battery if possible */ } dahdi_txsig_t; typedef enum { @@ -431,31 +437,31 @@ typedef enum { /* Span flags */ #define DAHDI_FLAG_REGISTERED (1 << 0) #define DAHDI_FLAG_RUNNING (1 << 1) -#define DAHDI_FLAG_RBS (1 << 12) /* Span uses RBS signalling */ +#define DAHDI_FLAG_RBS (1 << 12) /*!< Span uses RBS signalling */ /* Channel flags */ -#define DAHDI_FLAG_DTMFDECODE (1 << 2) /* Channel supports native DTMF decode */ -#define DAHDI_FLAG_MFDECODE (1 << 3) /* Channel supports native MFr2 decode */ -#define DAHDI_FLAG_ECHOCANCEL (1 << 4) /* Channel supports native echo cancellation */ - -#define DAHDI_FLAG_HDLC (1 << 5) /* Perform HDLC */ -#define DAHDI_FLAG_NETDEV (1 << 6) /* Send to network */ -#define DAHDI_FLAG_PSEUDO (1 << 7) /* Pseudo channel */ -#define DAHDI_FLAG_CLEAR (1 << 8) /* Clear channel */ -#define DAHDI_FLAG_AUDIO (1 << 9) /* Audio mode channel */ - -#define DAHDI_FLAG_OPEN (1 << 10) /* Channel is open */ -#define DAHDI_FLAG_FCS (1 << 11) /* Calculate FCS */ +#define DAHDI_FLAG_DTMFDECODE (1 << 2) /*!< Channel supports native DTMF decode */ +#define DAHDI_FLAG_MFDECODE (1 << 3) /*!< Channel supports native MFr2 decode */ +#define DAHDI_FLAG_ECHOCANCEL (1 << 4) /*!< Channel supports native echo cancellation */ + +#define DAHDI_FLAG_HDLC (1 << 5) /*!< Perform HDLC */ +#define DAHDI_FLAG_NETDEV (1 << 6) /*!< Send to network */ +#define DAHDI_FLAG_PSEUDO (1 << 7) /*!< Pseudo channel */ +#define DAHDI_FLAG_CLEAR (1 << 8) /*!< Clear channel */ +#define DAHDI_FLAG_AUDIO (1 << 9) /*!< Audio mode channel */ + +#define DAHDI_FLAG_OPEN (1 << 10) /*!< Channel is open */ +#define DAHDI_FLAG_FCS (1 << 11) /*!< Calculate FCS */ /* Reserve 12 for uniqueness with span flags */ -#define DAHDI_FLAG_LINEAR (1 << 13) /* Talk to user space in linear */ -#define DAHDI_FLAG_PPP (1 << 14) /* PPP is available */ +#define DAHDI_FLAG_LINEAR (1 << 13) /*!< Talk to user space in linear */ +#define DAHDI_FLAG_PPP (1 << 14) /*!< PPP is available */ #define DAHDI_FLAG_T1PPP (1 << 15) -#define DAHDI_FLAG_SIGFREEZE (1 << 16) /* Freeze signalling */ -#define DAHDI_FLAG_NOSTDTXRX (1 << 17) /* Do NOT do standard transmit and receive on every interrupt */ -#define DAHDI_FLAG_LOOPED (1 << 18) /* Loopback the receive data from the channel to the transmit */ -#define DAHDI_FLAG_MTP2 (1 << 19) /* Repeats last message in buffer and also discards repeating messages sent to us */ +#define DAHDI_FLAG_SIGFREEZE (1 << 16) /*!< Freeze signalling */ +#define DAHDI_FLAG_NOSTDTXRX (1 << 17) /*!< Do NOT do standard transmit and receive on every interrupt */ +#define DAHDI_FLAG_LOOPED (1 << 18) /*!< Loopback the receive data from the channel to the transmit */ +#define DAHDI_FLAG_MTP2 (1 << 19) /*!< Repeats last message in buffer and also discards repeating messages sent to us */ -/* This is a redefinition of the flags from above to allow use of the kernel atomic bit testing and changing routines. +/*! This is a redefinition of the flags from above to allow use of the kernel atomic bit testing and changing routines. * See the above descriptions for DAHDI_FLAG_.... for documentation about function. */ enum { DAHDI_FLAGBIT_REGISTERED = 0, @@ -482,75 +488,75 @@ enum { struct dahdi_span { spinlock_t lock; - void *pvt; /* Private stuff */ - char name[40]; /* Span name */ - char desc[80]; /* Span description */ - const char *spantype; /* span type in text form */ - const char *manufacturer; /* span's device manufacturer */ - char devicetype[80]; /* span's device type */ - char location[40]; /* span device's location in system */ - int deflaw; /* Default law (DAHDI_MULAW or DAHDI_ALAW) */ - int alarms; /* Pending alarms on span */ + void *pvt; /*!< Private stuff */ + char name[40]; /*!< Span name */ + char desc[80]; /*!< Span description */ + const char *spantype; /*!< span type in text form */ + const char *manufacturer; /*!< span's device manufacturer */ + char devicetype[80]; /*!< span's device type */ + char location[40]; /*!< span device's location in system */ + int deflaw; /*!< Default law (DAHDI_MULAW or DAHDI_ALAW) */ + int alarms; /*!< Pending alarms on span */ int flags; - int irq; /* IRQ for this span's hardware */ - int lbo; /* Span Line-Buildout */ - int lineconfig; /* Span line configuration */ - int linecompat; /* Span line compatibility */ - int channels; /* Number of channels in span */ - int txlevel; /* Tx level */ - int rxlevel; /* Rx level */ - int syncsrc; /* current sync src (gets copied here) */ - unsigned int bpvcount; /* BPV counter */ - unsigned int crc4count; /* CRC4 error counter */ - unsigned int ebitcount; /* current E-bit error count */ - unsigned int fascount; /* current FAS error count */ - - int maintstat; /* Maintenance state */ - wait_queue_head_t maintq; /* Maintenance queue */ - int mainttimer; /* Maintenance timer */ + int irq; /*!< IRQ for this span's hardware */ + int lbo; /*!< Span Line-Buildout */ + int lineconfig; /*!< Span line configuration */ + int linecompat; /*!< Span line compatibility */ + int channels; /*!< Number of channels in span */ + int txlevel; /*!< Tx level */ + int rxlevel; /*!< Rx level */ + int syncsrc; /*!< current sync src (gets copied here) */ + unsigned int bpvcount; /*!< BPV counter */ + unsigned int crc4count; /*!< CRC4 error counter */ + unsigned int ebitcount; /*!< current E-bit error count */ + unsigned int fascount; /*!< current FAS error count */ + + int maintstat; /*!< Maintenance state */ + wait_queue_head_t maintq; /*!< Maintenance queue */ + int mainttimer; /*!< Maintenance timer */ - int irqmisses; /* Interrupt misses */ + int irqmisses; /*!< Interrupt misses */ - int timingslips; /* Clock slips */ + int timingslips; /*!< Clock slips */ - struct dahdi_chan **chans; /* Member channel structures */ + struct dahdi_chan **chans; /*!< Member channel structures */ /* ==== Span Callback Operations ==== */ - /* Req: Set the requested chunk size. This is the unit in which you must + /*! Req: Set the requested chunk size. This is the unit in which you must report results for conferencing, etc */ int (*setchunksize)(struct dahdi_span *span, int chunksize); - /* Opt: Configure the span (if appropriate) */ + /*! Opt: Configure the span (if appropriate) */ int (*spanconfig)(struct dahdi_span *span, struct dahdi_lineconfig *lc); - /* Opt: Start the span */ + /*! Opt: Start the span */ int (*startup)(struct dahdi_span *span); - /* Opt: Shutdown the span */ + /*! Opt: Shutdown the span */ int (*shutdown)(struct dahdi_span *span); - /* Opt: Enable maintenance modes */ + /*! Opt: Enable maintenance modes */ int (*maint)(struct dahdi_span *span, int mode); #ifdef DAHDI_SYNC_TICK - /* Opt: send sync to spans */ + /*! Opt: send sync to spans */ int (*sync_tick)(struct dahdi_span *span, int is_master); #endif /* ==== Channel Callback Operations ==== */ - /* Opt: Set signalling type (if appropriate) */ + /*! Opt: Set signalling type (if appropriate) */ int (*chanconfig)(struct dahdi_chan *chan, int sigtype); - /* Opt: Prepare a channel for I/O */ + /*! Opt: Prepare a channel for I/O */ int (*open)(struct dahdi_chan *chan); - /* Opt: Close channel for I/O */ + /*! Opt: Close channel for I/O */ int (*close)(struct dahdi_chan *chan); - /* Opt: IOCTL */ + /*! Opt: IOCTL */ int (*ioctl)(struct dahdi_chan *chan, unsigned int cmd, unsigned long data); - /* Opt: Native echo cancellation (simple) */ + /*! Opt: Native echo cancellation (simple) */ int (*echocan)(struct dahdi_chan *chan, int ecval); int (*echocan_with_params)(struct dahdi_chan *chan, struct dahdi_echocanparams *ecp, struct dahdi_echocanparam *p); @@ -561,31 +567,31 @@ struct dahdi_span { rbsbits function and we'll assert robbed bits for you. Be sure to set the DAHDI_FLAG_RBS in this case. */ - /* Opt: If the span uses A/B bits, set them here */ + /*! Opt: If the span uses A/B bits, set them here */ int (*rbsbits)(struct dahdi_chan *chan, int bits); - /* Option 2: If you don't know about sig bits, but do have their + /*! Option 2: If you don't know about sig bits, but do have their equivalents (i.e. you can disconnect battery, detect off hook, generate ring, etc directly) then you can just specify a sethook function, and we'll call you with appropriate hook states to set. Still set the DAHDI_FLAG_RBS in this case as well */ int (*hooksig)(struct dahdi_chan *chan, dahdi_txsig_t hookstate); - /* Option 3: If you can't use sig bits, you can write a function + /*! Option 3: If you can't use sig bits, you can write a function which handles the individual hook states */ int (*sethook)(struct dahdi_chan *chan, int hookstate); - /* Opt: Dacs the contents of chan2 into chan1 if possible */ + /*! Opt: Dacs the contents of chan2 into chan1 if possible */ int (*dacs)(struct dahdi_chan *chan1, struct dahdi_chan *chan2); - /* Opt: Used to tell an onboard HDLC controller that there is data ready to transmit */ + /*! Opt: Used to tell an onboard HDLC controller that there is data ready to transmit */ void (*hdlc_hard_xmit)(struct dahdi_chan *chan); /* Used by DAHDI only -- no user servicable parts inside */ - int spanno; /* Span number for DAHDI */ - int offset; /* Offset within a given card */ - int lastalarms; /* Previous alarms */ - /* If the watchdog detects no received data, it will call the + int spanno; /*!< Span number for DAHDI */ + int offset; /*!< Offset within a given card */ + int lastalarms; /*!< Previous alarms */ + /*! If the watchdog detects no received data, it will call the watchdog routine */ int (*watchdog)(struct dahdi_span *span, int cause); #ifdef CONFIG_DAHDI_WATCHDOG @@ -619,7 +625,7 @@ struct dahdi_transcoder { unsigned int srcfmts; unsigned int dstfmts; int (*operation)(struct dahdi_transcoder_channel *channel, int op); - /* Transcoder channels */ + /*! Transcoder channels */ struct dahdi_transcoder_channel channels[0]; }; @@ -634,103 +640,103 @@ struct dahdi_transcoder { struct dahdi_dynamic_driver { - /* Driver name (e.g. Eth) */ + /*! Driver name (e.g. Eth) */ char name[20]; - /* Driver description */ + /*! Driver description */ char desc[80]; - /* Create a new transmission pipe */ + /*! Create a new transmission pipe */ void *(*create)(struct dahdi_span *span, char *address); - /* Destroy a created transmission pipe */ + /*! Destroy a created transmission pipe */ void (*destroy)(void *tpipe); - /* Transmit a given message */ + /*! Transmit a given message */ int (*transmit)(void *tpipe, unsigned char *msg, int msglen); - /* Flush any pending messages */ + /*! Flush any pending messages */ int (*flush)(void); struct dahdi_dynamic_driver *next; }; -/* Receive a dynamic span message */ +/*! \brief Receive a dynamic span message */ void dahdi_dynamic_receive(struct dahdi_span *span, unsigned char *msg, int msglen); -/* Register a dynamic driver */ +/*! \brief Register a dynamic driver */ int dahdi_dynamic_register(struct dahdi_dynamic_driver *driver); -/* Unregister a dynamic driver */ +/*! \brief Unregister a dynamic driver */ void dahdi_dynamic_unregister(struct dahdi_dynamic_driver *driver); -/* Receive on a span. The DAHDI interface will handle all the calculations for +/*! Receive on a span. The DAHDI interface will handle all the calculations for all member channels of the span, pulling the data from the readchunk buffer */ int dahdi_receive(struct dahdi_span *span); -/* Prepare writechunk buffers on all channels for this span */ +/*! Prepare writechunk buffers on all channels for this span */ int dahdi_transmit(struct dahdi_span *span); -/* Abort the buffer currently being receive with event "event" */ +/*! Abort the buffer currently being receive with event "event" */ void dahdi_hdlc_abort(struct dahdi_chan *ss, int event); -/* Indicate to DAHDI that the end of frame was received and rotate buffers */ +/*! Indicate to DAHDI that the end of frame was received and rotate buffers */ void dahdi_hdlc_finish(struct dahdi_chan *ss); -/* Put a chunk of data into the current receive buffer */ +/*! Put a chunk of data into the current receive buffer */ void dahdi_hdlc_putbuf(struct dahdi_chan *ss, unsigned char *rxb, int bytes); -/* Get a chunk of data from the current transmit buffer. Returns -1 if no data +/*! Get a chunk of data from the current transmit buffer. Returns -1 if no data * is left to send, 0 if there is data remaining in the current message to be sent * and 1 if the currently transmitted message is now done */ int dahdi_hdlc_getbuf(struct dahdi_chan *ss, unsigned char *bufptr, unsigned int *size); -/* Register a span. Returns 0 on success, -1 on failure. Pref-master is non-zero if +/*! Register a span. Returns 0 on success, -1 on failure. Pref-master is non-zero if we should have preference in being the master device */ int dahdi_register(struct dahdi_span *span, int prefmaster); -/* Allocate / free memory for a transcoder */ +/*! Allocate / free memory for a transcoder */ struct dahdi_transcoder *dahdi_transcoder_alloc(int numchans); void dahdi_transcoder_free(struct dahdi_transcoder *ztc); -/* Register a transcoder */ +/*! \brief Register a transcoder */ int dahdi_transcoder_register(struct dahdi_transcoder *tc); -/* Unregister a transcoder */ +/*! \brief Unregister a transcoder */ int dahdi_transcoder_unregister(struct dahdi_transcoder *tc); -/* Alert a transcoder */ +/*! \brief Alert a transcoder */ int dahdi_transcoder_alert(struct dahdi_transcoder_channel *ztc); -/* Unregister a span */ +/*! \brief Unregister a span */ int dahdi_unregister(struct dahdi_span *span); -/* Gives a name to an LBO */ +/*! \brief Gives a name to an LBO */ char *dahdi_lboname(int lbo); -/* Tell DAHDI about changes in received rbs bits */ +/*! \brief Tell DAHDI about changes in received rbs bits */ void dahdi_rbsbits(struct dahdi_chan *chan, int bits); -/* Tell DAHDI abou changes in received signalling */ +/*! \brief Tell DAHDI abou changes in received signalling */ void dahdi_hooksig(struct dahdi_chan *chan, dahdi_rxsig_t rxsig); -/* Queue an event on a channel */ +/*! \brief Queue an event on a channel */ void dahdi_qevent_nolock(struct dahdi_chan *chan, int event); -/* Queue an event on a channel, locking it first */ +/*! \brief Queue an event on a channel, locking it first */ void dahdi_qevent_lock(struct dahdi_chan *chan, int event); -/* Notify a change possible change in alarm status on a channel */ +/*! \brief Notify a change possible change in alarm status on a channel */ void dahdi_alarm_channel(struct dahdi_chan *chan, int alarms); -/* Notify a change possible change in alarm status on a span */ +/*! \brief Notify a change possible change in alarm status on a span */ void dahdi_alarm_notify(struct dahdi_span *span); -/* Initialize a tone state */ +/*! \brief Initialize a tone state */ void dahdi_init_tone_state(struct dahdi_tone_state *ts, struct dahdi_tone *zt); -/* Get a given MF tone struct, suitable for dahdi_tone_nextsample. */ +/*! \brief Get a given MF tone struct, suitable for dahdi_tone_nextsample. */ struct dahdi_tone *dahdi_mf_tone(const struct dahdi_chan *chan, char digit, int digitmode); /* Echo cancel a receive and transmit chunk for a given channel. This @@ -756,13 +762,13 @@ extern u_char __dahdi_lin2mu[16384]; extern u_char __dahdi_lin2a[16384]; #endif -/* Used by dynamic DAHDI -- don't use directly */ +/*! \brief Used by dynamic DAHDI -- don't use directly */ void dahdi_set_dynamic_ioctl(int (*func)(unsigned int cmd, unsigned long data)); -/* Used by DAHDI HPEC module -- don't use directly */ +/*! \brief Used by DAHDI HPEC module -- don't use directly */ void dahdi_set_hpec_ioctl(int (*func)(unsigned int cmd, unsigned long data)); -/* Used privately by DAHDI. Avoid touching directly */ +/*! \brief Used privately by DAHDI. Avoid touching directly */ struct dahdi_tone { int fac1; int init_v2_1; @@ -772,7 +778,7 @@ struct dahdi_tone { int init_v2_2; int init_v3_2; - int tonesamples; /* How long to play this tone before + int tonesamples; /*!< How long to play this tone before going to the next (in samples) */ struct dahdi_tone *next; /* Next tone in this sequence */ -- cgit v1.2.3