View AT75C1212_880653.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

1 features ? software module dedicated to voice processing and multi-way conferencing optimized for the at75 series smart internet appliance processor (siap ? ) includes several run-time configurable stand-alone algorithms ? g.723.1 dual-rate vocoder (5.3 kbps/6.4 kbps) ? vad/cng silence compression (annexe a of g.723.1) ? g.711 -law or a-law compression (64 kbps) ? arbitrary tone generator ? dtmf detector ? echo canceller itu-t g.723.1 and g.711 standard-compliant either up to two decode channels with g.723.1 standard, or up to four decode channels with g.711 standard available with a uclinux ? device driver overview the AT75C1212 multi-way conferencing software module is designed to run on the oakdspcore ? subsystem of the at75 series smart internet appliance processor. it implements commonly-used voice processing algorithms: low bit-rate g.723.1 vocoder for multimedia communication. silence compression algorithm to efficiently handle periods of silence during communication. high bit-rate voice compression algorithm. arbitrary tone generator that can be used to generate any dual-tone or single-tone frequency during a programmable duration. dtmf detector to decode incoming dtmf signaling. an echo canceller that eliminates the near-end echo. the implemented algorithms have a number of parameters which can be programmed at run time. these parameters modify the behavior of the dsp algorithms in such a manner that they comply with the applicable standards under most situations. they also allow the AT75C1212 to cope with many non-standard situations often encoun- tered on private telephone infrastructures. moreover, the AT75C1212 module is able to perform multi-way conferencing. either up to two independent decode channels with g.723.1 or up to four decode channels with either -law or a-law compression are available with no penalty on the voice quality. the AT75C1212 takes advantage of the at75 mailbox to exchange data with the on- chip arm7tdmi ? core. the organization of the data communication channel makes it easy to integrate the AT75C1212 interface into most operating systems. for developers using uclinux, a specific device driver is supplied, thereby assuring the extension of uclinux capabilities to the complete functionality of the AT75C1212 mod- ule in a seamless manner. this document is made up of three sections: 1. functional description of the supported algorithms. 2. description of the low level software interface. 3. description of the uclinux device driver and full integration of AT75C1212 functionality. note: mixing low-level and driver-level programming should be avoided. smart internet appliance processor (siap ? ) AT75C1212 multi-way conferencing software module rev. 2663a?intap?07/02
2 AT75C1212 2663a?intap?07/02 functional description a functional block diagram of the AT75C1212 multi-way conferencing software module is given in figure 1. figure 1. block diagram g.723.1 dual rate vocoder this algorithm can be used for compressing the speech or other audio signal compo- nents of a multimedia service at a very low bit rate. this coder has two bit rates associated with it: 5.3 and 6.4 kbps. the higher bit rate has better quality; it is based on multi pulse maximum likelihood quantization (mp-mlq) technique. the lower bit rate gives good quality and provides system designers with additional flexibility. this rate is based on an algebraic code linear pre-diction (acelp) technique. this coder operates on 30 ms speech frames of 16-bit linear pcm samples (sampling frequency is 8 khz). an algorithmic delay of 7.5 ms is to be taken into account before getting an encoded voice data frame. that leads to a total delay of 37.5 ms. the result- ing encoded frames are 20 bytes long for 5.3 kbps rate and 24 bytes long for 6.4 kbps rate. the encoding rate can be chosen by means of a configuration command sent to the dsp. (see ?request notification messages? on page 9.) vad/cng voice activity detection (vad) and comfort noise generator (cng) algorithms are designed to work hand-in-hand with the g.723.1 vocoder. silence compression tech- niques are used to reduce the transmitted bit rate during silent intervals of speech. the vad side detects those silent intervals. cng is used to produce a noise that matches the actual background noise. cng uses information provided by vad to encode silent intervals into silence insertion descriptor (sid) frames that are 4 bytes long. it also re- synthesizes 16-bit linear pcm samples of background noise with a sid frame input. the vad/cng feature can be enabled or not by means of a configuration command sent to the dsp. (see ?request notification messages? on page 9.) g.711 -law and a-law voice compression -law and a-law are logarithmic compression techniques applied to speech signals. they are done by simple operations that give no delay and excellent quality of speech. however, the bit rate is very high (each 16-bit linear pcm speech sample gives an 8-bit compressed sample leading to 64 kbps) making this feature useful only for broadband data networks. the compression/decompression algorithm can be chosen by means of a configuration command send to the dsp. (see ?request notification messages? on page 9.) g.723.1 encoder + vad/cng g.711 -law/a-law encoder g.711 -law/a-law decoder (up to four intances) g.723.1 decoder + cng (up to two intances) dtmf detection tone generation adc dac to handset from handset analog signals digital signals echo path echo cancellation
3 AT75C1212 2663a ? intap ? 07/02 echo cancellation operation the AT75C1212 contains an echo cancellation unit to eliminate near-end echo. this unit is based on an adaptive fir filter, which computes the expected echo and a sub- tractor, which removes it from the transmitted signal. since the echo characteristics can slowly vary with time, an adaptive algorithm continuously updates the echo model. a block diagram of the echo canceller is shown in figure 2 below. figure 2. block diagram of echo canceller multi-way conferencing AT75C1212 module allows several decoding channels to be active at the same time (up to two decode channels with g.723.1 standard or up to four with either pcm -law or pcm a-law). dtmf detector the dtmf detection task detects and decodes the 16 standard dtmf signals, in com- pliance with the itu-t q.24 recommendation, with programmable threshold levels. the application program, to comply with special (i.e. non-standard) situations, can tune some parameters of the algorithm. in order to detect the dtmf signal, a bank of eight resonant band pass filters is used. the central frequency of each filter corresponds to one of the eight nominal values employed by standard dtmf generators. the power level at each filter output is used to check for signal presence, signal condition require- ments, and character condition requirements. adc dac adaptive algorithm fir other processing algorithms
4 AT75C1212 2663a ? intap ? 07/02 figure 3. dtmf detector block diagram the eight band pass filters are centered on the eight frequencies defined in the itu-t q.24 specification. the bandwidth is specified according to the tolerance established in this standard. each filter rejects at least 20 db of the other seven frequencies. the power level is obtained by averaging the instantaneous energy during a window of 2 ms for each of the eight filtered signals. the detection of a dtmf signal requires that the following conditions be met: one frequency of each group is above a specified level. the power level difference between the low group tone and the high group tone is within a given interval (twist). the power level of the highest tone of each group is above a specified level above the other frequencies of the same group. signal condition detector 697 hz 770 hz 652 hz 941 hz 1209 hz 1336 hz 1477 hz 1633 hz power level power level power level power level power level power level power level power level out of band rejection character condition status signal in
5 AT75C1212 2663a ? intap ? 07/02 the character condition is fulfilled when: the signal condition is preceded by a different character recognition condition or by the continuous non-existence of a signal condition for a specified duration (silence). the signal condition for the same two tones exists continuously for a specified duration. when the signal condition is satisfied for less than a specified duration, the character is rejected. once the character condition exists, it is unaffected by an interval shorter than a specified duration. tone generator the tone generation task generates a pure sine wave or a dual tone with programmable frequencies, amplitudes and duration. low level interface this section describes how the AT75C1212 software is uploaded into the dsp sub- system program memory. it also describes how the application software running on the arm and the AT75C1212 running on the dsp subsystem exchange information through dual port mailboxes (dpmb). this section assumes in-depth knowledge of the arm/dsp subsystem interface mail- box system. voice module upload while the dsp subsystem is held in reset, its program memory is made visible in the arm memory space. this allows the arm application to write a binary image of the dsp software very easily. when the dsp subsystem is taken out of reset, its program memory is switched from the arm memory space back to the dsp program space just before the first instruction is fetched. this process is illustrated in figure 4. figure 4. voice module upload note: 1. bit ra in register siap_md. asb arm core reset oak subsystem siap_md.ra x-ram y-ram p-bus oak program memory (1)
6 AT75C1212 2663a ? intap ? 07/02 upload process a typical dsp program uses a number of initialized variables. typically, the initial values are stored in the program space, and copied into their ram location by the dsp start-up routine. this leads to the following statements: just after the boot routine has initialized the variables, the dsp subsystem exhibits high redundancy since the same values exist in both program and data memories. the initial values stored in the program memory waste space and are not used during operation. to improve the program memory usage, the software is loaded in two consecutive steps. a small data initialization program is first loaded and executed. this program just initializes the x- and y-ram to the values expected by the audio decoder software. when the initialization is done, the program sends a data_init_done status message to the arm application through the status mailbox. then, the dsp subsystem is put in reset and the program itself is loaded. this code has no data init start-up routine. it assumes the rams are already initialized, which saves program space. when the software is ready to work, it sends a sw_init_done status message through the status mailbox. the mailbox operation and status messages are described in the section ? mailbox usage ? on page 7. binary image format when the system is idle, the AT75C1212 module is stored in the arm memory space, possibly in non-volatile memory. the module contains the data initialization code, the application code, and additional formatting data. the various fields of the AT75C1212 binary image are described in table 1. dual-port mail box configuration the dual-port mail box (dpmb) is programmed in configuration 0 (as defined in the at75c dsp subsystem datasheet) and gives the configuration shown in table 2 on page 7. all the mailboxes allow read/write access from both sides. arbitration is done using the semaphores. table 1 . binary image fields field name offset from start of file (bytes) length (bytes) description init_offset 0 4 defines the position of the data initialization code from the beginning of the module image. init_length 4 4 defines the length of the data initialization code (16-bit words). valid between 0 and 24576. sw_offset 8 4 defines the position of the audio decoder program from the beginning of the module image. sw_lenghth 12 4 defines the length of the audio decoder code (16-bit words). valid between 0 and 24576. init_code 16 2*init_length binary code of the data initialization program. sw_code 16 + 2*init_length 2*sw_length binary code of the application program.
7 AT75C1212 2663a ? intap ? 07/02 note: 1. base address is 0xfa000000. mailbox access arm-to-oak mailboxes before accessing the arm-to-oak mailboxes, the arm must check that the correspond- ing semaphore is cleared to 0. then it can read or write the mailbox data. when the data access is done, it must set the semaphore to 1 to notify the oak that new data has arrived. oak-to-arm mailboxes the arm is notified that new data is available in a mailbox when the corresponding semaphore is raised to 1, possibly triggering an interrupt. then the arm can access the mailbox. when the access is finished, the arm must clear the semaphore to release the mailbox. mailbox usage this section describes the specific purpose of each mailbox. the exchanged information is formatted in structured messages. the message format and semantics are described in sections ? request notification messages ? on page 9 and ? status notification mes- sages ? on page 15. mailbox 0: rx encoded voice data used by the arm to get from the oak encoded speech frames (either g.711 data or g.723.1 data) mailbox 1 to 4: tx encoded voice data used by the arm to provide to the oak encoded speech frames (either g.711 data or g.723.1 data). mailbox 5: oak memory access the arm has the ability to send requests to read or write any location of the dsp mem- ories, either in program or data space. this is useful for two purposes: dsp software debug programming of the dsp peripherals under the arm application control mailbox 6: request notification this mailbox is used by the arm to pass requests to the dsp. these requests trigger specific tasks in the dsp software. for example, request notification messages are used to start or to stop the telephony algorithms. mailbox 7: status notification this mailbox is used by the dsp software to send status information. for example, a status notification message is sent by the dsp software at the end of the data initializa- tion to notify the arm application that the data has been initialized. table 2 . dpmb configuration mailbox # offset from base (1) length direction semaphore address (1) usage 0 0x000 0x80 arm -> oak 0x200 rx voice data 1 0x040 0x80 arm <- oak 0x204 tx voice data 1 2 0x080 0x40 arm -> oak 0x208 tx voice data 2 3 0x0c0 0x40 arm -> oak 0x20c tx voice data 3 4 0x100 0x40 arm -> oak 0x210 tx voice data 4 5 0x140 0x40 arm <- oak 0x214 dsp memory access 6 0x180 0x40 arm -> oak 0x218 request notification 7 0x1c0 0x40 arm <- oak 0x21c status notification
8 AT75C1212 2663a ? intap ? 07/02 tx/rx encoded voice data the first two mailboxes deal with speech compressed frames. each byte sent through the mailbox is put in a 16-bit word where low byte is the original byte value and in high byte are flags. assuming the data to be transmitted is in ? char buf[0..n-1] ? , it is formatted in the mailbox as shown in table 3 (otherwise the frame is ignored). note: 1. with frame_start = 0x8000 and frame_end = 0x4000 delivered frames are of variable length: the length is encoded within the first two bits of buf[0] for g.723.1: ? buf[0] & 0x3 = 0 -> 24 bytes at a rate of 6.3 kbits per second ? buf[0] & 0x3 = 1 -> 20 bytes for a rate of 5.3 kbits per second ? buf[0] & 0x3 = 2 -> 4 bytes for silence compression frames ? buf[0] & 0x3 = 3 -> 1 byte: it follows a 4-byte frame while the silence scheme is unchanged if the system is in g.711 mode, frames are 32 bytes long, independent of the contents of buf[0]. oak memory access the arm has the ability to send requests to read or write any location of the oak mem- ories, either in program or data space. to achieve this, the mailbox 5 is divided into four fields: command field (mailbox base + 0): this is a request id that tells what kind of operation is to be performed. valid codes are: ? 0x0001: program memory read ? 0x0002: program memory write ? 0x0003: data memory read ? 0x0004: data memory write address field (base + 1 16-bit word): should be written with the address location to be accessed. this is the value of the address as it is seen by the oak. length field (base + 2 16-bit words): should be written with the number of consecutive locations to access. data field (base + 3 16-bit words and following): for write access, should be filled with the values to write. for read access, contains the read values requested by the previous command. example of use: write 0x1234 into data location 0xabcd of the 0ak: 1. wait for *(0xfa000214) == 0, i.e., the semaphore is cleared 2. *(0xfa000140) = 0x0004 // data write command 3. *(0xfa000142) = 0xabcd // this is the address 4. *(0xfa000144) = 0x0001 // only one word to write 5. *(0cfa000146) = 0x1234 // this is the value 6. *(0xfa000214) = 1 // notify the oak ta ble 3. speech frame format (1) word 0 ... word i (i = 1... n - 2) ... word n - 1 frame_start | buf[0] ... 0x0000 | buf[i] ... frame_end | buf[n - 1]
9 AT75C1212 2663a ? intap ? 07/02 example of use: read data locations 0xabcd and 0xabce from oak: 1. wait for *(0xfb000214) == 0, i.e. the semaphore is cleared 2. *(0xfa000140) = 0x0003 // data read command 3. *(0xfa000142) = 0xabcd // this is the first address to read 4. *(0xfa000144) = 0x0002 // two words to read 5. *(0xfa000214) = 1 // notify the oak 6. wait for the semaphore to go back to 0. 7. read 0xfa000146 and 0xfa000148 to get the requested values. request notification messages request messages are used by the arm to trigger specific tasks running on the dsp. these messages are always formatted in the same way. figure 5 describes this format. figure 5. request notification message format a message always begins with a length field. this field contains the number of words of the message, excluding the length field itself. the request_id field is uniquely defined to designate the type of request. each request can be followed by a variable but well-defined number of parameter fields. these fields contain additional data needed to handle the request. the description of the supported request messages is listed below. it is forbidden for the arm application to issue unsupported messages. however, should the arm application issue an unsupported or malformed request, the oak software must recover correctly. decoding configuration request the decoding configuration request is sent to the oak before any voice decoding operation. example: 0x0003 0x0201 0x0000 0x0004 this request will set up decode channel 0 with g.723.1 standard. mailbox base address length words length request_id parameter[0] ... parameter[length - 2] unused... 16 bits ta ble 4. decoding configuration request word 0 0x0003 message length = 0x0003 word 1 0x0201 request id = 0x0201 word 2 tx_id tx channel ? sid. valid:0to3 word 3 tx_type tx channel ? stype: g.723.1: tx_type = 0x0004 -law: tx_type = 0x0000 a-law: tx_type = 0x0008
10 AT75C1212 2663a ? intap ? 07/02 encoding configuration request the encoding configuration request is sent to the oak before any voice data encoding operation. example: 0x0002 0x0202 0x0004 this request will set up record channel with g.723.1 standard. volume configuration request the volume configuration request is sent to the oak to set volume parameters. volume up request the volume up request is sent to the oak to increase the speakerphone volume. it can be sent at anytime. volume down request the volume down request is sent to the oak to lower the speakerphone volume. it can be sent at anytime. ta ble 5. encoding configuration request word 0 0x0002 message length = 0x0002 word 1 0x0202 request id = 0x0202 word 2 rx_type rx channel ? s type: g.723.1: rx_type = 0x0004 -law: rx_type = 0x0000 a-law: rx_type = 0x0008 ta ble 6. volume configuration request word 0 0x0003 message length = 0x0003 word 1 0x0300 request id = 0x0300 word 2 micr_gain = 0x1000 * 10e(db/20) gain for the microphone input. valid: 0x0040 (- 36 db) to 0x7fff (+18 db) word 3 spkr_gain = 0x1000 * 10e(db/20) gain for the speakerphone input. valid: 0x0040 (- 36 db) to 0x7fff (+18 db) ta ble 7. volume up request word 0 0x0001 message length = 0x0001 word 1 0x0301 request id = 0x0301 ta ble 8. volume down request word 0 0x0003 message length = 0x0001 word 1 0x0300 request id = 0x0302
11 AT75C1212 2663a ? intap ? 07/02 g.723.1 configuration request the g.723.1 configuration request should be sent to the oak before enabling any g.723.1 encoding operation, otherwise the default configuration will be used (6.4 kbits/s rate, vad/cng disabled). echo cancellation configuration request the echo cancellation configuration request should be sent to the oak before enabling any echo cancellation operation, otherwise the default configuration will be used. echo cancellation step-size adjust request the echo cancellation step-size adjust request can be sent to the oak at any time during the echo cancellation operation in order to enhance convergence characteristics. ta ble 9. g.723.1 configuration request word 0 0x0003 message length = 0x0003 word 1 0x0400 request id = 0x0400 word 2 workrate work rate for encoding, valid values: 0: 6.4 kbits/s rate 1: 5.3 kbits/s rate word 3 usevx 0: disable vad for encoding 1: enable vad for encoding table 10. echo cancellation configuration request word 0 0x0006 message length = 0x0006 word 1 0x0860 request id = 0x0860 word 2 echo_size filter size in blocks of 16 ? valid: 1 to 15 (between 16 and 240 filter coefficients) default: 4 (64 coefficients: cancellation up to an echo path of 8ms) word 3 echo_update number of coefficients updated at each sample interval. it must be a sub-multiple of the filter size (otherwise an invalid parameter status is generated) default: 64 (all the filter is updated) word 4 echo_stepsz step size default: 0x7f00 word 5 echo_timecst time constant of power estimation filter (ms) default: 32 ms word 6 echo_mucalc time interval between calculations of normalized step size in milliseconds. default: 1 ms table 11. echo cancellation step-size adjust request word 0 0x0002 message length = 0x0002 word 1 0x0863 request id = 0x0863 word 3 echo_stepsz step size
12 AT75C1212 2663a ? intap ? 07/02 start decoding request the start decoding request is sent to the oak to start decode operations as configured by the decoding configuration request. stop decoding request the stop decoding request is sent to the oak to stop one of the active decode channels as configured by the decoding configuration request. start record request the start record request is sent to the oak to start the recording operation as configured by encoding configuration request. stop record request the stop record request is sent to the oak to stop the record channel as configured by multi-way configuration request. start echo cancellation request the start echo cancellation request is sent to the oak to start echo cancellation opera- tions on one channel. stop echo cancellation request the stop echo cancellation request is sent to the oak to stop echo cancellation on one channel. table 12. start decoding request word 0 0x0002 message length = 0x0002 word 1 0x0401 request id = 0x0401 word 2 tx_id tx channel ? sid. valid: 0 to 3 table 13. stop decoding request word 0 0x0002 message length = 0x0002 word 1 0x0402 request id = 0x0402 word 2 tx_id tx channel ? sid. valid: 0 to 3 table 14. start record request word 0 0x0001 message length = 0x0001 word 1 0x0403 request id = 0x0403 table 15. stop record request word 0 0x0001 message length = 0x0001 word 1 0x0404 request id = 0x0404 table 16. start echo cancellation request word 0 0x0001 message length = 0x0001 word 1 0x0861 request id = 0x0861 table 17. stop echo cancellation request word 0 0x0001 message length = 0x0001 word 1 0x0862 request id = 0x0862
13 AT75C1212 2663a ? intap ? 07/02 dtmf detection configuration request example: 0x0009 0x0830 0x0020 0x0020 0x2000 0x2000 0x4000 0x4000 0x001e 0x001e: this message configures the dtmf detector with a detection level of 33 db below the reference level for each group. the minimum difference level between the strongest fre- quency in a group and the others of the same group must be at least of 18 db. the maximum difference level between the two groups must be at most 12 db. in order to recognize a character, the signal must last for a minimum of 30 ms and then be followed by 30 ms of silence. dtmf detection start request dtmf detection is started as soon as the dsp unit receives the dtmf detection start request. dtmf detection stop request dtmf detection is stopped as soon as the dsp unit receives the dtmf detection stop request. table 18. dtmf detection configuration request word 0 0x0009 message length = 0x0009 word 1 0x0830 request id = 0x0830 word 2 dtmfdet_lowthres = 65535 * 10e(db/10) low group power detection threshold (default: - 40db) word 3 dtmfdet_highthres = 65535* 10e(db/10) high group power detection threshold (default: - 40db) word 4 dtmfdet_lowrel = 65535* 10e(db/20) minimum difference level between the strongest frequency in the low group and the other of the same group (default: -20db) word 5 dtmfdet_highrel = 65535* 10e(db/20) minimum difference level between the strongest frequency in the high group and the other of the same group (default: -20db) word 6 dtmfdet_postwist = 65535* 10e(db/10) maximum low to high twist (default: -8db) word 7 dtmfdet_ negtwist = 65535* 10e(db/10) maximum high to low twist (default: -8db) word 8 dtmfdet_duration duration of signal condition for character recognition in milliseconds (default: 30 ms). word 9 dtmfdet_silence duration of silence condition for character recognition in milliseconds (default: 30 ms). table 19. dtmf detection start request word 0 0x0001 message length = 0x0001 word 1 0x0831 request id = 0x0831 table 20. dtmf detection stop request word 0 0x0001 message length = 0x0001 word 1 0x0832 request id = 0x0832
14 AT75C1212 2663a ? intap ? 07/02 tone generation configuration request example: 0x000a 0x0801 0x6d4b 0x429f 0x4000 0x3fc4 0x6efb 0x3000 0x0080 0x0080 0x0007 this message configures the generator to emit a dual tone with: first component. 697 hz tone 6 db below the reference level. second component. 1336 hz tone 8.5 db below the reference level. dtmf digit ? 2 ? will have been recognized. the tone is emitted as soon as the dsp unit receives the request. after 128 ms of signal and 128 ms of silence, a tone generation done status message will be emitted. table 21. tone generation configuration request word 0 0x000a message length = 0x000a word 1 0x0800 request id = 0x0800 word 2 32768 * cos (pi* tone_freq /4000) words 2 and 3 define the frequency of the first generated tone. word 3 32768 * sin (pi* tone_freq /4000) word 4 tone_level = 32768 * 10e(db/20) level of the first generated tone. word 5 32768 * cos (pi* tone_freq /4000) words 5 and 6 define the frequency of the second component of generated tone. word 6 32768 * sin (pi* tone_freq /4000) word 7 tone_level = 32768 * 10e(db/20) level of the second generated tone. word 8 tone_duration duration of the generated tone in milliseconds 0x0000 means unlimited duration. word 9 silence _duration duration of the silence following the tone in milliseconds 0x0000 means unlimited duration. word 10 tone_start bit 0 : 0: causes the generator to wait for a tone generation start request (request id 0x0801) before the tone is generated. 1: the generation starts immediately. bit 1 : 0: adds the tone to all other signals emitted on the speaker. 1: all other signals are blocked while the tone is generated. bit 2 : 0: single tone generation, parameters of the second component are ignored. 1: dual tone generation.
15 AT75C1212 2663a ? intap ? 07/02 tone generation start request the tone starts as soon as the dsp unit receives tone generation start request. a tone generation configuration request (request id 0x0800) should be issued before the tone generation start request is sent. if not, the behavior of the tone generator is unpredictable. tone generation stop request the tone stops as soon as the dsp unit receives the tone generation stop request. this request can be used to stop an unlimited tone generation, or to halt the generator before the predefined duration has elapsed (early termination). status notification messages status messages are used by the oak to inform the arm application that a specific event has occurred, or to respond to an earlier request. these messages are always formatted in the same way. figure 6 describes this format. figure 6. status notification message format a status message always begins with a length field. this field contains the number of words of the message, excluding the length field itself. the status_id field is uniquely defined to designate the type of status. each status can be followed by a variable but well-defined number of parameter fields. these fields contain additional status information. the description of the supported status messages is listed below. it is forbidden for the oak program to issue unsupported status messages. however, should the oak program issue an unsupported or malformed status message, the arm application must recover correctly. table 22. tone generation start request word 0 0x0001 message length = 0x0001 word 1 0x0801 request id = 0x0801 table 23. tone generation stop request word 0 0x0001 message length = 0x0001 word 1 0x0802 request id = 0x0802 mailbox base address length words length status_id parameter[0] ... parameter[length - 2] unused... 16 bits
16 AT75C1212 2663a ? intap ? 07/02 AT75C1212 module initialization status this initialization status message is issued when the AT75C1212 module has finished initializing itself and is ready to accept request messages. the arm should not issue any request messages before this status message has been received. bad format status the oak issues a bad format status message when it has received a request message in which the length field is not compatible with the request type. the oak ignores the corresponding malformed request. unknown request status the oak issues an unknown request status message when it has received a request message with an unsupported request id field. bad parameter status the oak issues a bad parameter status message when it has received a request mes- sage with a parameter having an invalid value. g.723.1 encoding stopped status message the g.723.1 encoding stopped status message is issued if the encode task was stopped by a stop encoding request (request id 0x0404). table 24. AT75C1212 module initialization status word 0 0x0001 message length = 0x0001 word 1 0x8002 request id = 0x8002 table 25. bad format status word 0 0x0002 message length = 0x0002 word 1 0x80ff status id = 0x80ff word 2 bad_format_value contains the request id of the malformed request message. table 26. unknown request status word 0 0x0002 message length = 0x0002 word 1 0x80fe status id = 0x80fe word 2 unknown_req_value contains the request id of the malformed request message. table 27. bad parameter status word 0 0x0002 message length = 0x0002 word 1 0x80fd status id = 0x80fd word 2 unknown_req_value contains the request id of the malformed request message. table 28. g.723.1 encoding stopped status message word 0 0x0001 message length = 0x0001 word 1 0x8404 status id = 0x8404
17 AT75C1212 2663a ? intap ? 07/02 g.711 encoding stopped status message the g.711 encoding stopped status message is issued if the encode task was stopped by a stop encoding request (request id 0x0404). g.723.1 decoding stop status message this status message is issued if one g.723.1 decoding task was stopped by a stop decoding request (request id 0x0402). g.711 decoding stop status message this status message is issued if one g.711 decoding task was stopped by a stop decod- ing request (request id 0x0402). dtmf detection status the dtmf detection status message is issued each time a valid dtmf digit is detected on the line-in input signal. the association of the digit codes to each of the sixteen possible dtmf tones is shown in table 33. table 29. g.711 encoding stopped status message word 0 0x0001 message length = 0x0001 word 1 0x8414 status id = 0x8414 table 30. g.723.1 decoding stop status message word 0 0x0002 message length = 0x0002 word 1 0x8402 status id = 0x8402 word 2 tx_n g.723.1 decode channel which has been stopped. valid: 0 to 3 table 31. g.711 decompression stopped status message word 0 0x0002 message length = 0x0002 word 1 0x8412 status id = 0x8412 word 2 tx_n g.711 decoding channel which has been stopped. valid: 0 to 3 table 32. dtmf detection status word 0 0x0002 message length = 0x0002 word 1 0x8831 status id = 0x8831 word 2 dtmfdet_digit detected dtmf digit table 33. map of dtmf tones and associated digit code 1209 hz 1336 hz 1477 hz 1633 hz 697 hz 1 0x01 2 0x02 3 0x03 a 0x0d 770 hz 4 0x04 5 0x05 6 0x06 b 0x0e 852 hz 7 0x07 8 0x08 9 0x09 c 0x0f 941 hz * 0x0b 0 0x0a # 0x0c d 0x00
18 AT75C1212 2663a ? intap ? 07/02 tone generation status the tone generation status message is issued when the tone duration has elapsed. it is not issued if the tone was stopped by a tone generation stop request (request id 0x0802). AT75C1212 device driver the AT75C1212 software module is supplied with a device driver for uclinux. this device driver integrates all the AT75C1212 functionalities into the uclinux kernel. the features of the AT75C1212 modules can be accessed through the standard uclinux api. this api is documented in the following section. AT75C1212 device driver overview under uclinux, the device drivers are accessed through file system entries. the AT75C1212 device driver is a character type driver. the associated virtual file can be opened, read from, written to and closed like any regular file. the major role of the device driver is to redefine the file access methods, so that the application can interact with the underlying device, as if it were a file, through the standard file manipulation functions. it provides the application with an abstraction layer which hides the low level interface on top of which it sits. the AT75C1212 device driver is operated through several file systems: /dev/g723encoder0 which is used for g.723.1 encoding operations, /dev/g723decoder0 to /dev/g723decoder3 which are used for g.723.1 decoding operations, /dev/g711encoder0 which is used for g.711 -law/a-law encoding operations, /dev/g711decoder0 to /dev/g711decoder3 which are used for g.711 -law/a-law decoding operations, /dev/tones which is used for dtmf detection and arbitrary tone generation. g723.1 encoder driver operations the g.723.1 encoder driver redefines the following file manipulation functions: int open(const char *path, int flags, mode_t mode); int read(int fd, void *buf, int count); int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); int close(int fd); additionally, the ioctl function controls additional features of the AT75C1212 which are not accessible with the other methods. these special commands are described below. the prototype of the ioctl function is: int ioctl(int fd, int request, char *argp); open method synopsis #include #include #include int open(const char *path, int flags); table 34. tone generation status word 0 0x0001 message length = 0x0001 word 1 0x8802 status id = 0x8802
19 AT75C1212 2663a ? intap ? 07/02 description the /dev/g723encoder0 virtual file must be opened prior to any encoding operation on the g723.1 encoder device driver. this is done with the open method, the same as for any regular file. the main operation performed by the open method of the device driver is to load and initialize the corresponding dsp software in the dsp subsystem. when this initialization is successful, the open system call converts the file ? path ? name ("/dev/g723encoder0" in this case) into a file descriptor. this file descriptor is a non-neg- ative integer which will be used in subsequent i/o operations such as read, ioctl, etc. ? flags ? should be o_rdonly which request opening the file in read-only mode. ? flags ? may also be bitwise-or'd with o_nonblock. in this case, neither the open nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. return values open() returns the new file descriptor, or -1 if an error occurred. in the latter case, the global variable errno is set appropriately to reflect the cause of error. possible values of errno are: enodev: this indicates that the underlying hardware does not exist or is not supported. one reason can be corruption of the binary dsp software which could not be loaded into the dsp subsystem. ebusy: the underlying hardware is busy. most probably there is another process using the same resource. enomem: a memory allocation requested by the driver failed. this happens when the system memory is full. example int fd = open("/dev/g723encoder0", o_rdonly | o_nonblock); this opens the g.723.1 encoder device driver in read mode. it selects non blocking i/o for read operations. the file descriptor is returned in ? fd ? .if ? fd ? is positive, the g723.1 encoder device is readily available for read operations.
20 AT75C1212 2663a ? intap ? 07/02 close method synopsis #include int close(int fd); description when the g.723.1 encoder device is no longer needed by the application, it can be closed to release system resources. this is done through the close method. the param- eter is the file descriptor of the file to be closed. return values close() returns 0 on success, or -1 if an error occurred. in the latter case the global vari- able is set appropriately to reflect the cause of error. the only possible value for errno is ebadf which means that ? fd ? is not a valid file descriptor. example close(fd); this closes the g.723.1 encoder device. read method synopsis #include int read(int fd, void *buf, int count); description as for any file descriptor, the read() method attempts to read ? count ? bytes from ? fd ? into the buffer starting at ? buf ? . when ? fd ? is a file descriptor attached to /dev/g723encoder0, the bytes read correspond to g.723.1 frames. both blocking and non-blocking reads are supported. in blocking mode, read() will return only when there are g.723.1 valid frames available to read. although the process is blocked, it is safely put on a system wait queue and does not consume cpu time. in non-blocking mode, the read function returns immediately even if no data is available. in this case the return value is -1 and errno is set to eagain. return values on success, the number of bytes read is returned. it is not an error if this number is smaller than the number of bytes requested. this may happen, for example, because fewer bytes are actually available at that moment, or because read was interrupted by a signal. on error, -1 is returned and errno is set appropriately. possible values for errno follow: eagain: non-blocking i/o has been selected using o_nonblock and no data was immediately available. ebadf: ? fd ? is not a valid descriptor. einval: the /dev/g723encoder0 file was not open for reading. efault: ? buf ? is outside the accessible address space. example ret = read(fd,buf,256); this reads at most 256 bytes from file descriptor ? fd ? (assumed here to be related to /dev/g723encoder0), and stores them into the memory location pointed to by ? buf ? . select method synopsis #include #include
21 AT75C1212 2663a ? intap ? 07/02 #include int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); description select() waits for a number of file descriptors to change status. the main usage of select() is to check if data (g.723.1 frames) are available for reading without having to actually read the data. in particular, when blocking operation is selected, it advises if a read access will block or not. this is similar to a polling operation. three independent sets of descriptors are watched. 1. thoselistedin ? readfds ? will be watched to see if characters become available for reading. 2. those in ? writefds ? will be watched to see if a write will not block (not used there). 3. those in ? exceptfds ? will be watched for exceptions (not used there). on exit, the sets are modified in place to indicate which descriptors actually changed status. four macros are provided to manipulate the sets. fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor from a set. fd_isset tests to see if a descriptor is part of the set. this is useful after select returns. ? n ? is the highest-numbered descriptor in any of the three sets, plus 1. ? timeout ? is an upper limit on the amount of time elapsed before select returns. it may be zero, causing select to return immediately. if timeout is null (no timeout), select can block indefinitely. return values on success, select returns the number of descriptors contained in the descriptor sets, which may be zero if the timeout expires before an event occurs. on error, -1 is returned, and errno is set appropriately. the sets and timeout become undefined, therefore their contents are not to be relied upon after an error. example fd_set rfds; struct timeval tv; int retval; /* initialize file descriptor list */ fd_zero(&rfds); fd_set(df, &rfds); /* define delay */ tv.tv_sec = 0; tv.tv_usec = 50000; retval = select(df+1, &rfds, null, null, &tv); /* df supposed to be a file descriptor related to /dev/g723encoder0 */ if (retval > 0) printf("g.723.1 frame received.\n"); else printf("g.723.1 frame not received within 50 ms.\n"); this code checks if a g.723.1 frame has been received. the time-out is 50 ms.
22 AT75C1212 2663a ? intap ? 07/02 ioctl method synopsis #include int ioctl(int fd, int request, char *argp); description the ioctl() function manipulates the underlying device parameters of the g723.1 encoder device. ? fd ? is the file descriptor upon which ioctl() will act. it should be related to the /dev/g723encoder0 virtual file. ? request ? defines which predefined command to send to the g.723.1 encoder device. some commands may require additional arguments which are stored or received in the buffer pointed to by ? argp ? . the ioctl() requests supported by the g.723.1 device driver are described below: rec_config: this command is used to configure the encoding operation of the multiway driver with g.723.1 payload. this must be done before performing any other operation on the device. there is no additional argument. g723_config: this command is used to configure the characteristics of the g.723.1 encoder algorithm. an additional parameter is used as defined below: struct g723cod_args { unsigned short enc_rate; unsigned short vad_cng; }; the fields and the values to be written are those defined in the section ? low level inter- face ? on page 5. this should be done before any other operation on the device is performed if default values are not appropriate. start_record: this command is used to start the g.723.1 encoding operation. there is no additional argument. stop_record: this command is used to stop the g.723.1 encoding operation. there is no additional argument. echocancel_config: this command is used to configure the characteristics of the echo canceller algorithm. an additional parameter is used as defined below: struct echocancel_args { unsigned short echo_size; unsigned short echo_update; unsigned short echo_stepsz; unsigned short echo_timeconst; unsigned short echo_mucalc; }; the fields and the values to be written are those defined in the ? request notification messages ? section of this document. this should be done before performing any other operation on the device if default values are not appropriate. echocancel_start: this command is used to start the echo cancelling operation. there is no additional argument. echocancel_stop: this command is used to stop the echo cancelling operation. there is no additional argument. oakmem_access: this command is used to read/write the memory space of the oak, either program or data. it should be used with caution (primarily for oak debug). an additional parameter is used as defined below:
23 AT75C1212 2663a ? intap ? 07/02 struct oakmem_args { unsigned short command; unsigned short address; unsigned short length; unsigned short data[29]; }; thefieldsandthevaluestobewrittenarethosedefinedinthesection: ? oak memory access ? on page 8. example struct g723cod_args { unsigned short enc_rate; unsigned short vad_cng; } *g723_conf; fd723_conf->enc_rate=1;//5.3 kbps rate for encoder g723_conf->vad_cng=1;//vad/cng algorithm active ioctl(fd, g723_config, g723_conf); this configures the g.723.1 algorithm. ? fd ? refers to /dev/g723encoder0 virtual file. g723.1 decoder driver operations the g.723.1 decoder driver redefines the following file manipulation functions: int open(const char *path, int flags, mode_t mode); int write(int fd, void *buf, int count); int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval timeout); int close(int fd); additionally, the ioctl function controls additional features of the AT75C1212 which are not accessible with the other methods. these special commands are described below. the prototype of the ioctl function is: int ioctl(int fd, int request, char *argp); these methods apply to the four devices "/dev/g723decodern" where n stands for 0,1,2,3. the four devices have the same major but have differing minor. open method synopsis #include #include #include int open(const char *path, int flags); description one /dev/g723decodern virtual file must be opened prior to any decoding operation on the corresponding g.723.1 decoder device driver. this is made with the open() method, the same as for any regular file. the main operation performed by the open() method of the device driver is to load and initialize the corresponding dsp software in the dsp subsystem. when this initialization is successful, the open system call converts the file ? path ? name ("/dev/g723decoder0" for example) into a file descriptor. this file descriptor is a non- negative integer which will be used in subsequent i/o operations such as write(), ioctl(), etc. ? flags ? should be o_wronly which requests opening the file in write-only mode.
24 AT75C1212 2663a ? intap ? 07/02 ? flags ? may also be bitwise-or'd with o_nonblock. in this case, neither the open nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. return values open ? return the new file descriptor ? ,or-1ifanerroroccurred.inthelattercase,theglo- bal variable errno is set appropriately to reflect the cause of error. possible values of errno are: enodev: this indicates that the underlying hardware does not exist or is not supported. one reason can be corruption of the binary dsp software which could not be loaded into the dsp subsystem. ebusy: the underlying hardware is busy. most probably there is another process using the same resource. enomem: a memory allocation requested by the driver failed. this happens when the system memory is full. example int fd = open("/dev/g723decoder0", o_wronly | o_nonblock); this opens the g.723.1 decoder device driver in write mode, decode channel chosen is 0. it selects non blocking i/o for write operations. the file descriptor is returned in ? fd ? .if ? fd ? is positive, the g.723.1 decoder device 0 is readily available for read operations. close method synopsis #include int close(int fd); description when the g.723.1 decoder device is no longer needed by the application, it can be closed to release system resources. this is done through the close() method. the parameter is the file descriptor of the file to be closed. return values close() returns 0 on success, or -1 if an error occurred. in the latter case the global vari- able is set appropriately to reflect the cause of error. the only possible value for errno is ebadf which means that fd is not a valid file descriptor. example close(fd); this closes the g.273 decoder device. write method synopsis #include int write(int fd, void *buf, int count); description as for any file descriptor, the write() method attempts to write ? count ? bytes from the buffer starting at buf to the file descriptor ? fd ? .when ? fd ? is a file descriptor attached to /dev/g723decodern, the bytes written correspond to the g.723.1 frames which are to be emitted by the g.723.1 decoder device. both blocking and non-blocking writes are supported. in blocking mode, write() will return only when the g.723.1 decoder device is ready to accept data. although the pro- cess is blocked, it is safely put on a system wait queue and does not consume cpu time.
25 AT75C1212 2663a ? intap ? 07/02 in non-blocking mode, the write function returns immediately even if no data is available. in this case the return value is -1 and errno is set to eagain. most often, the application will try again to write until the entire data is transferred. return values on success, the number of bytes written is returned. this corresponds to the number of g.723.1 bytes actually emitted. it is not an error if this number is smaller than the num- ber of bytes requested. this may happen, for example, because fewer bytes are actually acceptable at that moment due to lack of memory, or because write was interrupted by a signal. on error, -1 is returned and errno is set appropriately. possible values for errno follow: eagain: non-blocking i/o has been selected using o_nonblock and no data was immediately available. ebadf: ? fd ? is not a valid descriptor. einval: /dev/g723decodern file was not opened for writing. efault: ? buf ? is outside the accessible address space. example ret = write(fd,buf,256); this writes at most 256 bytes to file descriptor ? fd ? (assumed here to be related to one /dev/g723decodern), from the memory location pointed to by ? buf ? . select method synopsis #include #include #include int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); description select() waits for a number of file descriptors to change status. the main usage of select() is to check if data (g.723.1 frames) are available for writing without having to actually write the data. in particular, when blocking operation is selected, it indicates if a write access will block or not. this is similar to a polling operation. three independent sets of descriptors are watched. 1. thoselistedin ? readfds ? (not used there) will be watched to see if characters become available for reading. 2. those in ? writefds ? will be watched to see if a write will not block. 3. those in ? exceptfds ? will be watched for exceptions (not used there). on exit, the sets are modified in place to indicate which descriptors actually changed status. four macros are provided to manipulate the sets. fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor from a set. fd_isset tests to see if a descriptor is part of the set. this is useful after select returns. ? n ? is the highest-numbered descriptor in any of the three sets, plus 1.
26 AT75C1212 2663a ? intap ? 07/02 ? timeout ? is an upper limit on the amount of time elapsed before select returns. it may be zero, causing select to return immediately. if timeout is null (no timeout), select can block indefinitely. return on success, select() returns the number of descriptors contained in the descriptor sets, which may be zero if the timeout expires before an event occurs. on error, -1 is returned, and errno is set appropriately, the sets and timeout become undefined, therefore their contents are not to be relied upon after an error. example fd_set wfds; struct timeval tv; int retval; /* initialize file descriptor list */ fd_zero(&wfds); fd_set(df, &wfds); /* define delay */ tv.tv_sec = 0; tv.tv_usec = 50000; retval = select(df+1, null, &wfds, null, &tv); /* df supposed to be a file descriptor related to /dev/g723decodern */ if (retval > 0) printf("g.723.1 frame requested by dsp.\n"); else printf("no g.723.1 frame requested within 50 ms.\n"); this code checks if a g.723.1 frame is requested by the dsp. the time-out is 50 ms. ioctl method synopsis #include int ioctl(int fd, int request, char *argp); description the ioctl() function manipulates the underlying device parameters of the g.723.1 decoder devices. ? fd ? is the file descriptor upon which ioctl() will act. it is related to on of the /dev/g723decodern virtual file. ? request ? defines which predefined command to send to the g.723.1 decoder device. some commands may require additional arguments which are stored or received in the buffer pointed to by ? argp ? . the ioctl() requests supported by the g.723.1 decoder device driver are described below: dec_config: this command is used to configure the decoding operation of the multiway driver with g.723.1 payload. this must be done before performing any other operation on the device. there is no additional argument. start_decode: this command is used to start the g.723.1 decoding operation. there is no additional argument. stop_ decode: this command is used to stop the g.723.1 decoding operation. there is no additional argument. oakmem_access: this command is used to read/write the memory space of the oak, either program or data. it should be used with caution, (primarily for oak debug). an additional parameter is used as defined below: struct oakmem_args { unsigned short command;
27 AT75C1212 2663a ? intap ? 07/02 unsigned short address; unsigned short length; unsigned short data[29]; }; thefieldsandthevaluestobewrittenarethosedefinedinthesection: ? oak memory access ? on page 8. example ioctl(fd, dec_config, null); assume that ? fd ? is referring to /dev/g723decoder1. this ioctl configures the decode channel 1 with the g.723.1 payload. g.711 encoder driver operations the g.711 encoder driver redefines the following file manipulation functions: int open(const char *path, int flags, mode_t mode); int read(int fd, void *buf, int count); int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); int close(int fd); additionally, the ioctl() function controls additional features of the AT75C1212 which are not accessible with the other methods. these special commands are described below. the prototype of the ioctl() function is: int ioctl(int fd, int request, char *argp); open method synopsis #include #include #include int open(const char *path, int flags); description the /dev/g711encoder0 virtual file must be opened prior to any encoding operation on the g.711 encoder device driver. this is made with the open() method, the same as for any regular file. the main operation performed by the open() method of the device driver is to load and initialize the corresponding dsp software in the dsp subsystem. when this initialization is successful, the open system call converts the file ? path ? name ("/dev/g711encoder0" in this case) into a file descriptor. this file descriptor is a non-neg- ative integer which will be used in subsequent i/o operations such as read(), ioctl(), etc. ? flags ? should be o_rdonly which request opening the file in read-only mode. ? flags ? may also be bitwise-or'd with o_nonblock. in this case, neither the open nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. return values open return the new file descriptor, or -1 if an error occurred. in the latter case, the glo- bal variable errno is set appropriately to reflect the cause of error. possible values of errno are: enodev: this indicates that the underlying hardware does not exist or is not supported. one reason can be a corruption of the binary dsp software which could not be loaded into the dsp subsystem. ebusy: the underlying hardware is busy. most probably there is another process using the same resource.
28 AT75C1212 2663a ? intap ? 07/02 enomem: a memory allocation requested by the driver failed. this happens when the system memory is full. example int fd = open("/dev/g711encoder0", o_rdonly | o_nonblock); this opens the g.711 encoder device driver in read mode. it selects non blocking i/o for read operations. the file descriptor is returned in ? fd ? .if ? fd ? is positive, the g711 encoder device is readily available for read operations. close method synopsis #include int close(int fd); description when the g.711 encoder device is no longer needed by the application, it can be closed to release system resources. this is done through the close method. the parameter is the file descriptor of the file to be closed. return values close() returns 0 on success, or -1 if an error occurred. in the latter case the global vari- able is set appropriately to reflect the cause of error. the only possible value for errno is ebadf which means that ? fd ? is not a valid file descriptor. example close(fd); this closes the g.711 encoder device. read method synopsis #include int read(int fd, void *buf, int count); description as for any file descriptor, the read() method attempts to read ? count ? bytes from ? fd ? into the buffer starting at ? buf ? . when ? fd ? is a file descriptor attached to /dev/g711encoder0, the bytes read correspond to g.711 frames recognized by the g.711 encoder device. both blocking and non-blocking reads are supported. in blocking mode, read() will return only when there are g.711 valid frames available to read. although the process is blocked, it is safely put on a system wait queue and does not consume cpu time. in non-blocking mode, the read function returns immediately even if no data is available. in this case the return value is -1 and errno is set to eagain. return values on success, the number of bytes read is returned. it is not an error if this number is smaller than the number of bytes requested. this may happen, for example, because fewer bytes are actually available at that moment, or because read was interrupted by a signal. on error, -1 is returned and errno is set appropriately. possible values for errno follow: eagain: non-blocking i/o has been selected using o_nonblock and no data was immediately available. ebadf: fd is not a valid descriptor. einval: /dev/g711encoder0 file was not open for reading. efault: ? buf ? is outside the accessible address space. example ret = read(fd,buf,256);
29 AT75C1212 2663a ? intap ? 07/02 this reads at most 256 bytes from file descriptor ? fd ? (assumed here to be related to /dev/g711encoder0), and stores them into the memory location pointed to by ? buf ? . select method synopsis #include #include #include int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); description select() waits for a number of file descriptors to change status. the main usage of select() is to check if data (g.711 frames) are available for reading without having to actually read the data. in particular, when blocking operation is selected, it advises if a read access will block or not. this is similar to a polling operation. three independent sets of descriptors are watched: 1. thoselistedin ? readfds ? will be watched to see if characters become available for reading. 2. those in ? writefds ? will be watched to see if a write will not block (not used there) 3. those in ? exceptfds ? will be watched for exceptions (not used there). on exit, the sets are modified in place to indicate which descriptors actually changed status. four macros are provided to manipulate the sets: fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor from a set. fd_isset tests to see if a descriptor is part of the set. this is useful after select returns. ? n ? is the highest-numbered descriptor in any of the three sets, plus 1. ? timeout ? is an upper limit on the amount of time elapsed before select returns. it may be zero, causing select to return immediately. if timeout is null (no timeout), select can block indefinitely. return values on success, select returns the number of descriptors contained in the descriptor sets, which may be zero if the timeout expires before an event occurs. on error, -1 is returned, and errno is set appropriately, the sets and timeout become undefined, there- fore their contents are not to be relied upon after an error. example fd_set rfds; struct timeval tv; int retval; /* initialize file descriptor list */ fd_zero(&rfds); fd_set(df, &rfds); /* define delay */ tv.tv_sec = 0; tv.tv_usec = 5000; retval = select(df+1, &rfds, null, null, &tv); /* df supposed to be a file descriptor related to /dev/g711encoder0 */ if (retval > 0)
30 AT75C1212 2663a ? intap ? 07/02 printf("g.711 frame received.\n"); else printf("g.711 frame not received within 5 ms.\n"); this code checks if a g.711 frame has been received. the time-out is 5 ms. ioctl method synopsis #include int ioctl(int fd, int request, char *argp); description the ioctl() function manipulates the underlying device parameters of the g.711 encoder device. ? fd ? is the file descriptor upon which ioctl() will act. it should be related to the /dev/g711encoder0 virtual file. ? request ? defines which predefined command to send to the g.711 encoder device. some commands may require additional arguments which are stored or received in the buffer pointed to by argp. the ioctl() requests supported by the g.711 device driver are described below: rec_config: this command is used to configure the encoding operation of the multiway driver with the g.711 payload. this must be done before performing any other operation on the device. an additional parameter is used as defined below: int payload; this selects pcmu or pcma. the valid values to be written are those defined in the section ? low level interface ? on page 5. this should be done before any other operation is performed on the device if default values are not appropriate. start_record: this command is used to start the g.711 encoding operation. there is no additional argument. stop_record: this command is used to stop the g.711 encoding operation. there is no additional argument. echocancel_start: this command is used to start the echo cancelling operation. there is no additional argument. echocancel_stop: this command is used to stop the echo cancelling operation. there is no additional argument. oakmem_access: this command is used to read/write the memory space of the oak, either program or data. it should be used with caution, (primarily for oak debug). an additional parameter is used as defined below: struct oakmem_args { unsigned short command; unsigned short address; unsigned short length; unsigned short data[29]; }; thefieldsandthevaluestobewrittenarethosedefinedinthesection: ? oak memory access ? on page 8. example #define pcma 8 ioctl(g711, g711_config, pcma);
31 AT75C1212 2663a ? intap ? 07/02 this configures the encoding channel with pcma payload. g711 decoder driver operations the g711 decoder driver redefines the following file manipulation functions: int open(const char *path, int flags, mode_t mode); int write(int fd, void *buf, int count); int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); int close(int fd); additionally, the ioctl function controls additional features of the AT75C1212 which are not accessible with the other methods. these special commands are described below. the prototype of the ioctl function is: int ioctl(int fd, int request, char *argp); these methods apply to the four devices "/dev/g711decodern" where n stands for 0,1,2,3. the four devices have the same major but have differing minor. open method synopsis #include #include #include int open(const char *path, int flags); description one /dev/g711decodern virtual file must be opened prior to any decoding operation on corresponding g.711 decoder device driver. this is made with the open() method, the same as for any regular file. the main operation performed by the open() method of the device driver is to load and initialize the corresponding dsp software in the dsp subsystem. when this initialization is successful, the open system call converts the file ? path ? name ("/dev/g711decoder0" for example) into a file descriptor. this file descriptor is a non- negative integer which will be used in subsequent i/o operations such as write, ioctl, etc. ? flags ? should be o_wronly which requests opening the file in write-only mode. ? flags ? may also be bitwise-or'd with o_nonblock. in this case, neither the open nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. return values open return the new file descriptor, or -1 if an error occurred. in the latter case, the glo- bal variable errno is set appropriately to reflect the cause of error. possible values of errno are: enodev: this indicates that the underlying hardware does not exist or is not supported. one reason can be a corruption of the binary dsp software which could not be loaded into the dsp subsystem. ebusy: the underlying hardware is busy. most probably there is another process using the same resource. enomem: a memory allocation requested by the driver failed. this happens when the system memory is full. example int fd = open("/dev/g711decoder0", o_wronly | o_nonblock);
32 AT75C1212 2663a ? intap ? 07/02 this opens the g.711 decoder device driver in write mode, decode channel chosen is 0. it selects non blocking i/o for write operations. the file descriptor is returned in ? fd ? .if ? fd ? is positive, the g.711 decoder device 0 is readily available for write operations. close method synopsis #include int close(int fd); description when the g.711 decoder device is no longer needed by the application, it can be closed to release system resources. this is done through the close() method. the parameter is the file descriptor of the file to be closed. return values close() returns 0 on success, or -1 if an error occurred. in the latter case the global vari- able is set appropriately to reflect the cause of error. the only possible value for errno is ebadf which means that ? fd ? is not a valid file descriptor. example close(fd); this closes the g.711 decoder device. write method synopsis #include int write(int fd, void *buf, int count); description as for any file descriptor, the write method attempts to write ? count ? bytes from the buffer starting at ? buf ? to the file descriptor ? fd ? .when ? fd ? is a file descriptor attached to /dev/g711decodern, the bytes written correspond to the g.711 frames which are to be emitted by the g.711 decoder device. both blocking and non-blocking writes are supported. in blocking mode, write() will return only when the g.711 decoder device is ready to accept data. although the pro- cess is blocked, it is safely put on a system wait queue and does not consume cpu time. in non-blocking mode, the write function returns immediately even if no data is available. in this case the return value is -1 and errno is set to eagain. most often, the application will retry to write as far as the entire data is transferred. return values on success, the number of bytes written is returned. this corresponds to the number of g.711 bytes actually emitted. it is not an error if this number is smaller than the number of bytes requested. this may happen, for example, because fewer bytes are actually acceptable at that moment due to lack of memory, or because write was interrupted by a signal. on error, -1 is returned and errno is set appropriately. possible values for errno follow: eagain: non-blocking i/o has been selected using o_nonblock and no data was immediately available. ebadf: ? fd ? is not a valid descriptor. einval: the /dev/g711decodern file was not opened for writing. efault: ? buf ? is outside the accessible address space. example ret = write(fd,buf,256);
33 AT75C1212 2663a ? intap ? 07/02 this writes at most 256 bytes to file descriptor ? fd ? (assumed here to be related to one /dev/g711decodern), from the memory location pointed to by ? buf ? . select method synopsis #include #include #include int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); description select waits for a number of file descriptors to change status. the main usage of select is to check if data (g.711 frames) are available for writing without having to actually write the data. in particular, when blocking operation is selected, it indicates if a write access will block or not. this is similar to a polling operation. three independent sets of descriptors are watched: 1. thoselistedin ? readfds ? (not used there) will be watched to see if characters become available for reading. 2. those in ? writefds ? will be watched to see if a write will not block. 3. those in ? exceptfds ? will be watched for exceptions (not used there). on exit, the sets are modified in place to indicate which descriptors actually changed status. four macros are provided to manipulate the sets. fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor from a set. fd_isset tests to see if a descriptor is part of the set. this is useful after select returns. ? n ? is the highest-numbered descriptor in any of the three sets, plus 1. ? timeout ? is an upper limit on the amount of time elapsed before select returns. it may be zero, causing select to return immediately. if timeout is null (no timeout), select can block indefinitely. return values on success, select() returns the number of descriptors contained in the descriptor sets, which may be zero if the timeout expires before an event occurs. on error, -1 is returned, and errno is set appropriately, the sets and timeout become undefined, there- fore their contents are not to be relied upon after an error. example fd_set wfds; struct timeval tv; int retval; /* initialize file descriptor list */ fd_zero(&wfds); fd_set(df, &wfds); /* define delay */ tv.tv_sec = 0; tv.tv_usec = 5000; retval = select(df+1, null, &wfds, null, &tv); /* df supposed to be a file descriptor related to /dev/g711decodern */ if (retval > 0)
34 AT75C1212 2663a ? intap ? 07/02 printf("g.711 frame requested by dsp.\n"); else printf("no g.711 frame requested within 5 ms.\n"); this code checks if a g.711 frame is requested by the dsp. the time-out is 5 ms. ioctl method synopsis #include int ioctl(int fd, int request, char *argp); description the ioctl function manipulates the underlying device parameters of the g.711 decoder devices. ? fd ? is the file descriptor upon which ioctl will act. it is related to the /dev/g711decodern virtual file. ? request ? defines which predefined command to send to the g.711 decoder device. some commands may require additional arguments which are stored or received in the buffer pointed to by ? argp ? . the ioctl requests supported by the g.711 decoder device driver are described below: dec_config: this command is used to configure the decoding operation of the multiway driver with g.711 payload. an additional parameter is used as defined below: int payload; // this selects pcmu or pcma the valid values to be written are those defined in the section ? low level interface ? on page 5. this must be done before any other operation is performed on the device. start_decode: this command is used to start the g.711 decoding operation. there is no additional argument. stop_ decode: this command is used to stop the g.711 decoding operation. there is no additional argument. oakmem_access: this command is used to read/write the memory space of the oak, either program or data. it should be used with caution, (primarily for oak debug). an additional parameter is used as defined below: struct oakmem_args { unsigned short command; unsigned short address; unsigned short length; unsigned short data[29]; }; thefieldsandthevaluestobewrittenarethosedefinedinthesection: ? oak memory access ? on page 8. example #define pcmu 0 ioctl(fd, dec_config, pcmu); assume that ? fd ? is referring to /dev/g711decoder2. this configures decoding channel 2 with pcmu payload. tones & dtmf driver operations the tones driver redefines the following file manipulation functions: int open(const char *path, int flags, mode_t mode);
35 AT75C1212 2663a ? intap ? 07/02 int read(int fd, void *buf, int count); int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); int close(int fd); additionally, the ioctl() function controls additional features of the AT75C1212 which are not accessible with the other methods. these special commands are described below. the prototype of the ioctl function is: int ioctl(int fd, int request, char *argp); open method synopsis #include #include #include int open(const char *path, int flags); description the /dev/tones virtual file must be opened prior to any operation on the tones device driver. this is made with the open() method, the same as for any regular file. the main operation performed by the open() method of the device driver is to load and initialize the corresponding dsp software in the dsp subsystem. when this initialization is successful, the open system call converts the file ? path ? name ("/dev/tones" in this case) into a file descriptor. this file descriptor is a non-negative inte- ger which will be used in subsequent i/o as with read, ioctl, etc. ? flags ? should be o_rdonly which request opening the file in read-only mode. ? flags ? may also be bitwise-or'd with o_nonblock. in this case, neither the open nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. return values open return the new file descriptor, or -1 if an error occurred. in the latter case, the glo- bal variable errno is set appropriately to reflect the cause of error. possible values of errno are: enodev: this indicates that the underlying hardware does not exist or is not supported. one reason can be a corruption of the binary dsp software which could not be loaded into the dsp subsystem. ebusy: the underlying hardware is busy. most probably there is another process using the same resource. enomem: a memory allocation requested by the driver failed. this happens when the system memory is full. example int fd = open("/dev/tones", o_rdonly | o_nonblock); this opens the tones device driver in read mode. it selects non blocking i/o for read operations. the file descriptor is returned in ? fd ? .if ? fd ? is positive, the tones device is readily available for read operations. close method synopsis #include int close(int fd);
36 AT75C1212 2663a ? intap ? 07/02 description when the tones device is no longer needed by the application, it can be closed to release system resources. this is done through the close() method. the parameter is the file descriptor of the file to be closed. return values close returns 0 on success, or -1 if an error occurred. in the latter case the global vari- able is set appropriately to reflect the cause of error. the only possible value for errno is ebadf which means that ? fd ? is not a valid file descriptor. example close(fd); this closes the tones device. read method synopsis #include int read(int fd, void *buf, int count); description as for any file descriptor, the read() method attempts to read ? count ? bytes from ? fd ? into the buffer starting at ? buf ? . when ? fd ? is a file descriptor attached to /dev/tones, the bytes read correspond to either dtmf digits, if dtmf detection has been activated, or a tone_generation_done code, if tone generation has been activated. the mapping between the value of each byte and the dtmf digit is as follows: byte value of tone_generation_done = 0xba both blocking and non-blocking reads are supported. in blocking mode, read will return only when there are tones valid frames available to read. although the process is blocked, it is safely put on a system wait queue and does not consume cpu time. in non-blocking mode, the read function returns immediately even if no data is available. in this case the return value is -1 and errno is set to eagain. return values on success, the number of bytes read is returned. it is not an error if this number is smaller than the number of bytes requested. this may happen, for example, because fewer bytes are actually available at that moment, or because read was interrupted by a signal. on error, -1 is returned and errno is set appropriately. possible values for errno follow: eagain: non-blocking i/o has been selected using o_nonblock and no data was immediately available. ebadf: ? fd ? is not a valid descriptor. table 35. dtmf digit and byte value map byte value dtmf digit byte value dtmf digit 0x01 '1 ? 0x09 '9' 0x02 '2 ? 0x0a '0' 0x03 '3 ? 0x0b '*' 0x04 '4 ? 0x0c '#' 0x05 '5 ? 0x0d 'a' 0x06 '6 ? 0x0e 'b' 0x07 '7 ? 0x0f 'c' 0x08 '8 ? 0x00 'd'
37 AT75C1212 2663a ? intap ? 07/02 einval: the /dev/tones file was not open for reading. efault: ? buf ? is outside the accessible address space. example ret = read(fd,buf,256); this reads at most 256 bytes from file descriptor ? fd ? (assumed here to be related to /dev/tones), and stores them into the memory location pointed to by ? buf ? . select method synopsis #include #include #include int select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); description select waits for a number of file descriptors to change status. the main usage of select() is to check if data (dtmf digits or tone_generation_done code) are available for reading without having to actually read the data. in particular, when blocking operation is selected, it allows to know if a read access will block or not. this is similar to a polling operation. three independent sets of descriptors are watched. 1. thoselistedin ? readfds ? will be watched to see if characters become available for reading. 2. those in ? writefds ? will be watched to see if a write will not block (not used there), 3. those in ? exceptfds ? will be watched for exceptions (not used there). on exit, the sets are modified in place to indicate which descriptors actually changed status. four macros are provided to manipulate the sets. fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor from a set. fd_isset tests to see if a descriptor is part of the set. this is useful after select returns. ? n ? is the highest-numbered descriptor in any of the three sets, plus 1. ? timeout ? is an upper limit on the amount of time elapsed before select returns. it may be zero, causing select to return immediately. if timeout is null (no timeout), select can block indefinitely. return values on success, select returns the number of descriptors contained in the descriptor sets, which may be zero if the timeout expires before an event occurs. on error, -1 is returned, and errno is set appropriately, the sets and timeout become undefined, there- fore their contents are not to be relied upon after an error. example fd_set rfds; struct timeval tv; int retval; /* initialize file descriptor list */ fd_zero(&rfds); fd_set(df, &rfds);
38 AT75C1212 2663a ? intap ? 07/02 /* define delay */ tv.tv_sec = 5; tv.tv_usec = 0; retval = select(df+1, &rfds, null, null, &tv); //df supposed to be a file descriptor related to /dev/tones if (retval > 0) printf("dtmf digit detected.\n"); else printf("no dtmf digit detected within 5 s.\n"); this code checks if a dtmf digit has been detected. the time-out is 5 ms. ioctl method synopsis #include int ioctl(int fd, int request, char *argp); description the ioctl() function manipulates the underlying device parameters of the tones device. ? fd ? is the file descriptor upon which ioctl() will act. it should be related to the /dev/tones virtual file. ? request ? defines which predefined command to send to the tones device. some com- mands may require additional arguments which are stored or received in the buffer pointed to by ? argp ? . the ioct() requests supported by the tones device driver are described below: dtmfdet_config: this command is used to configure the characteristics of the dtmf detector. an additional parameter is used as defined below: struct dtmfdet_args{ unsigned short lowthres; unsigned short highthres; unsigned short lowrel; unsigned short highrel; unsigned short postwist; unsigned short negtwist; unsigned short duration; unsigned short silence; }; the fields and the values to be written are those defined in the section ? low level inter- face ? on page 5. dtmfdet_start: this command is sent to start the dtmf detection immediately. there is no additional argument. dtmfdet_stop: this command is sent to stop the dtmf detection immediately. there is no additional argument. tonegen_config: this command is used to configure the characteristics of the arbitrary tone signals. an additional parameter is used as defined below: struct tonegen_args{ unsigned short cosw1; unsigned short sinw1; unsigned short lev1; unsigned short cosw2; unsigned short sinw2;
39 AT75C1212 2663a ? intap ? 07/02 unsigned short lev2; unsigned short signal_len; unsigned short silence_len; unsigned short start; }; the fields and the values to be written are those defined in the section ? request notifi- cation messages ? on page 9. tonegen_start: this command is sent to start the generation of a tone immediately. there is no additional argument. tonegen_stop: this command is sent to stop the generation of a tone immediately. there is no additional argument. echocancel_config: this command is used to configure the characteristics of the echo canceller algorithm. an additional parameter is used as defined below: struct echocancel_args { unsigned short echo_size; unsigned short echo_update; unsigned short echo_stepsz; unsigned short echo_timeconst; unsigned short echo_mucalc; }; the fields and the values to be written are those defined in the ? request notification messages ? section of this document. this should be done before any other kind of operation on the device if default values do not suit. echocancel_start: this command is used to start the echo cancelling operation. there is no additional argument. echocancel_stop: this command is used to stop the echo cancelling operation. there is no additional argument. oakmem_access: this command is used to read/write the memory space of the oak, either program or data. it should be carefully used, mainly for oak debug purpose. an additional parameter is used as defined below: struct oakmem_args { unsigned short command; unsigned short address; unsigned short length; unsigned short data[29]; }; the fields and the values to be written are those defined in the section: ? oak memory access ? on page 8. example struct tonegen_args{ unsigned short cosw1; unsigned short sinw1; unsigned short lev1; unsigned short cosw2; unsigned short sinw2; unsigned short lev2; unsigned short signal_len; unsigned short silence_len; unsigned short start;
40 AT75C1212 2663a ? intap ? 07/02 }* tone_args; // 1st frequency component tone_args-> cosw1 = 0x5a82; // 1khz tone tone_args-> sinw1 = 0x5a83; // tone_args-> lev1 = 0x4000; // -6db under full scale reference // 2nd frequency component not used here tone_args-> cosw2 = 0; tone_args-> sinw2 = 0; tone_args-> lev1 = 0; tone_args-> signal_len = 500; // milliseconds tone_args-> silence_len = 500; // milliseconds tone_args-> start = 2; // wait for tone start request, single tone is generated ioctl(fd, tonegen_config, tone_args); this configures the arbitrary tone characteristics for an usual operation.
printed on recycled paper. ? atmel corporation 2002. atmel corporation makes no warranty for the use of its products, other than those expressly contained in the company ? s standard warranty whichisdetailedinatmel ? s terms and conditions located on the company ? s web site. the company assumes no responsibility for any errors which may appear in this document, reserves the right to change devices or specifications detailed herein at any time without notice, and does not make any commitment to update the information contained herein. no licenses to patents or other intellectual property of atmel are granted by the company in connection with the sale of atmel products, expressly or by implication. atmel ? s products are not authorized for use as critical components in life support devices or systems. atmel headquarters atmel operations corporate headquarters 2325 orchard parkway san jose, ca 95131 tel 1(408) 441-0311 fax 1(408) 487-2600 europe atmel sarl route des arsenaux 41 case postale 80 ch-1705 fribourg switzerland tel (41) 26-426-5555 fax (41) 26-426-5500 asia room 1219 chinachem golden plaza 77 mody road tsimhatsui east kowloon hong kong tel (852) 2721-9778 fax (852) 2722-1369 japan 9f, tonetsu shinkawa bldg. 1-24-8 shinkawa chuo-ku, tokyo 104-0033 japan tel (81) 3-3523-3551 fax (81) 3-3523-7581 memory 2325 orchard parkway san jose, ca 95131 tel 1(408) 441-0311 fax 1(408) 436-4314 microcontrollers 2325 orchard parkway san jose, ca 95131 tel 1(408) 441-0311 fax 1(408) 436-4314 la chantrerie bp 70602 44306 nantes cedex 3, france tel (33) 2-40-18-18-18 fax (33) 2-40-18-19-60 asic/assp/smart cards zone industrielle 13106 rousset cedex, france tel (33) 4-42-53-60-00 fax (33) 4-42-53-60-01 1150 east cheyenne mtn. blvd. colorado springs, co 80906 tel 1(719) 576-3300 fax 1(719) 540-1759 scottish enterprise technology park maxwell building east kilbride g75 0qr, scotland tel (44) 1355-803-000 fax (44) 1355-242-743 rf/automotive theresienstrasse 2 postfach 3535 74025 heilbronn, germany tel (49) 71-31-67-0 fax (49) 71-31-67-2340 1150 east cheyenne mtn. blvd. colorado springs, co 80906 tel 1(719) 576-3300 fax 1(719) 540-1759 biometrics/imaging/hi-rel mpu/ high speed converters/rf datacom avenue de rochepleine bp 123 38521 saint-egreve cedex, france tel (33) 4-76-58-30-00 fax (33) 4-76-58-34-80 e-mail literature@atmel.com web site http://www.atmel.com 2663a ? intap ? 07/02 0m at m e l ? is the registered trademark of atmel; siap ? is the trademark of atmel. arm ? and arm7tdmi ? are registered trademarks of arm ltd.; oakdspcore ? is a registered trademark of dsp group inc.; uclinux ? is the registered trademark of lineo inc. other terms and product names may be the trademarks of others.

▲Up To Search▲

Price & Availability of AT75C1212

	To Download AT75C1212 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .