Reference Driver

ManualsBrandsMaxim Integrated ManualsHardware73M1866B/73M1966B

Simplifying System Integration

73M1866B/73M1966B

Reference Driver User Guide

June 22, 2009

Rev. 2.7

UG_1x66B_015

Summary of content (98 pages)

PAGE 1
Simplifying System IntegrationTM 73M1866B/73M1966B Reference Driver User Guide June 22, 2009 Rev. 2.
PAGE 2
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 © 2010 Teridian Semiconductor Corporation. All rights reserved. Teridian Semiconductor Corporation is a registered trademark of Teridian Semiconductor Corporation. Simplifying System Integration is a trademark of Teridian Semiconductor Corporation. Linux is a registered trademark of Linus Torvalds. Asterisk is a registered trademark of Digium, Inc. All other trademarks are the property of their respective owners.
PAGE 3
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide Table of Contents 1 2 3 4 5 6 Introduction ................................................................................................................................... 7 1.1 Purpose and Scope ................................................................................................................. 7 1.2 Conventions Used in this Guide ...............................................................................................
PAGE 4
73M1866B/73M1966B Reference Driver User Guide 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 UG_1x66B_015 6.1.12 M1966_PCM_ACTIVATION_CLEAR ......................................................................... 31 6.1.13 M1966_PCM_ACTIVATION_GET ............................................................................. 31 6.1.14 M1966_CNTRY_NMBR_GET.................................................................................... 32 6.1.15 M1966_GET_COUNTRY_CONFIG .........................................
PAGE 5
UG_1x66B_015 7.6 7.7 7.8 7.9 7.10 7.11 7.12 7.13 7.14 73M1866B/73M1966B Reference Driver User Guide M1966_PULSE_DIAL_t ......................................................................................................... 76 M1966_PULSE_DIAL_PARAM_t ........................................................................................... 77 M1966_THRESH_OVERRIDE_t ............................................................................................ 77 M1966_SAMPLE_RATE_SELECTION...........
PAGE 6
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 Figures Figure 1: Driver Architecture .................................................................................................................... 7 Figure 2: Driver Functional Block Diagram ............................................................................................... 9 Figure 3: Loopback Modes ....................................................................................................................
PAGE 7
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 1 Introduction This document describes the capabilities of the 73M1866B/73M1966B Reference Driver. This driver software is provided for use and integration by Teridian customers on their individual platforms. The intention of this Reference Driver is to provide a customizable framework that is independent of processor and operating system.
PAGE 8
73M1866B/73M1966B Reference Driver User Guide 1.2 UG_1x66B_015 Conventions Used in this Guide This document uses the following conventions: • • 1.3 Software code, IOCTL names, FXO events, data types, and Linux commands are presented in Courier font. A table with a blue header is a summary table. A table with a gray header is a detail table.
PAGE 9
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 2 Overview 2.1 Driver Architecture The driver provides a framework by which applications can leverage the features of the chipset. The main interface of the driver (IOCTLs) provides an abstraction layer for monitoring and control of the device status. Device status is analyzed and processed by an independently running process based on predefined algorithms.
PAGE 10
73M1866B/73M1966B Reference Driver User Guide 2.2 UG_1x66B_015 Functional Overview Once installed, the driver is a self-contained module running independently along with the kernel processes. Its main purpose is to monitor the FXO line for various conditions, generates appropriated event when they occur, and to provide access to the 73M1x66B device for management purposes, via standard driver access methods such as open, close, select, ioctl, etc.
PAGE 11
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide The application is responsible for building up the IET using the IET table update IOCTL – M1966_MEASURE_UPDATE. This IOCTL can be used to create/update or to read back the current table entry (see Section 6.6.3 for details). 2.2.3.2 Measurement Procedure The driver is responsible for reading the raw value required at a given sample rate from the device.
PAGE 12
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 2.2.5 Loopback and Testing Modes The 1966B devices support six variations of loopback modes. Refer to the “Loopback and Testing Modes” section of the 73M1866B/73M1966B Data Sheet for more detail. Each loopback mode is designed to test connectivity at various points in the system.
PAGE 13
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 3 Driver Service Interface The Driver Service provides the link between the FXO device and the user application. First, the driver must be loaded and binded into the operating system environment before this service can be provided. Access to the driver is done via two file descriptors – the device and channel file descriptors.
PAGE 14
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 4 Country Specific Settings The 73M1x66B Reference Driver supports global compliance parameters for each DAA device it manages. When selected for a specific country code using M1966_CH_INIT, the following predefined parameters will be applied: 1. 2. 3. 4. 5. AC termination impedance – AC impedance register value. DC termination mask – DC mask value. Ring Detection – Ring detection threshold value.
PAGE 15
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 5 FXO Events The driver provides event service to the high level application by maintaining a FIFO queue of event structures, M1966_FXO_EVENT_t. Events are created by the driver to reflect various conditions as described in Section 5.2. Once created, this new event is added to the FIFO queue and the driver notifies the application layer via file descriptor status change mechanism.
PAGE 16
73M1866B/73M1966B Reference Driver User Guide 5.2 UG_1x66B_015 Event Identification 5.2.1 M1966_BATTERY_DROPPED This event occurs when the FXO line is disconnected from the telephone network. Parameters Data Type Name Description unsigned int event_id M1966_BATTERY_DROPPED. unsigned int channel_id Channel ID. unsigned int event_cnt Number of events that remain in the queue. unsigned int event_data1 N/A. unsigned int event_data2 N/A. unsigned int event_data3 N/A.
PAGE 17
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 5.2.4 M1966_ONH_NOPOH_DETECT This event is generated when a parallel phone goes back on hook while the FXO line is in on-hook state. Parameters Data Type Name Description unsigned int event_id M1966_ONH_NOPOH_DETECT. unsigned int channel_id Channel ID. unsigned int event_cnt Number of events that remain in the queue. unsigned int event_data1 N/A. unsigned int event_data2 N/A. unsigned int event_data3 N/A.
PAGE 18
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 5.2.7 M1966_RING_DETECT_START This event is generated at the beginning of the ring burst. Parameters Data Type Name Description unsigned int event_id M1966_RING_DETECT_START. unsigned int channel_id Channel ID. unsigned int event_cnt Number of events that remain in the queue. unsigned int event_data1 Ring burst frequency (in Hz). unsigned int event_data2 N/A. unsigned int event_data3 N/A. unsigned int event_data4 N/A. 5.2.
PAGE 19
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 5.2.10 M1966_OV_DETECT This event is generated on detection of an over voltage line condition. Parameters Data Type Name Description unsigned int event_id M1966_OV_DETECT. unsigned int channel_id Channel ID. unsigned int event_cnt Number of events that remain in the queue. unsigned int event_data1 N/A. unsigned int event_data2 N/A. unsigned int event_data3 N/A. unsigned int event_data4 N/A. 5.2.
PAGE 20
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 5.2.13 M1966_LINE_STATE This event is generated when the line state analysis process detects a change in the state of the line. The line state analysis process will monitor (under user control) the line current and/or voltage in both On and off hook states. This event indicates that either the user has requested the current line state or one of the programmable threshold states has become active or non active.
PAGE 21
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 5.2.16 M1966_DEVICE_RECOVERED This event is generated after the device is successfully recovered from a failure. Parameters Data Type Name Description unsigned int event_id M1966_DEVICE_RECOVERED. unsigned int channel_id Channel ID. unsigned int event_cnt Number of events that remain in the queue. unsigned int event_data1 N/A. unsigned int event_data2 N/A. unsigned int event_data3 N/A. unsigned int event_data4 N/A. 5.2.
PAGE 22
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6 IOCTL Commands Description Upon successful opening of a device or channel descriptor the application layer can control the operation of the device and the FXO channel. The application in user space communicates with the driver via standard Linux driver interface IOCTL calls.
PAGE 23
UG_1x66B_015 6.1 73M1866B/73M1966B Reference Driver User Guide Initialization and Configuration IOCTLs The following IOCTLs are defined to configure the 73M1x66B. Some commands pertain to device level configuration such as PCM interface parameters; these must be called using device descriptor, while others are channel level commands and must be called using channel descriptors. Table 1 provides a summary of the IOCTLs.
PAGE 24
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.1 M1966_CH_INIT Description Performs 73M1x66 channel initialization. This includes initialize all default registers and country specific threshold parameters. This IOCTL requires the country code listed in M1966_COUNTRY_CODE as input. The FXO channel will be initialized according to the default setting parameter of the input country code. The default setting parameter can be found in the 73m1966_cntry_tbl.c file.
PAGE 25
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.2 M1966_PCM_IF_CSET_OPMODE_SET Description Sets the 73M1x66 to operate in slave mode. The 73M1x66 is always in slave mode therefore this IOCTL merely returns 0.
PAGE 26
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.3 M1966_PCM_IF_CSET_FREQUENCY_SET Description If the incoming PCM frequency differs from the default value, then this IOCTL changes the 73M1x66 to the requested frequency.
PAGE 27
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.4 M1966_PCM_IF_CSET_RPOL_SET Description Sets receive edge polarity. #define M1966_PCM_IF_CSET_RPOL_SET _IOWR(0xA4,0xD2,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PCM_IF_CSET_RPOL_SET, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_PCM_IF_CSET_RPOL_SET I/O control identifier for this operation. unsigned long param 1 – Rising edge. 0 – Falling edge.
PAGE 28
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.6 M1966_PCM_IF_CSET_RCS_SET Description Sets receive clock slot. #define M1966_PCM_IF_CSET_RCS_SET _IOWR(0xA4,0xD4,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PCM_IF_CSET_RCS_SET, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_PCM_IF_CSET_RCS_SET I/O control identifier for this operation. unsigned long param Clock slot value from 0 to 7. Channel descriptor.
PAGE 29
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.8 M1966_PCM_CSET_TSLOT_RX_SET Description Sets receive PCM time slot. #define M1966_PCM_CSET_TSLOT_RX_SET _IOWR(0xA4,0xD6,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PCM_CSET_TSLOT_RX_SET, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_PCM_CSET_TSLOT_RX_SET I/O control identifier for this operation. unsigned long param PCM time slot value from 0 to 0x7F.
PAGE 30
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.10 M1966_PCM_CSET_COMPRESSION_SET Description Sets PCM data compression mode. #define M1966_PCM_CSET_COMPRESSION_SET _IOWR(0xA4,0xD8,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PCM_CSET_COMPRESSION_SET, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_PCM_CSET_COMPRESSION_SET I/O control identifier for this operation. unsigned long param Compression mode: 0 – Companded mode: A-law.
PAGE 31
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.12 M1966_PCM_ACTIVATION_CLEAR Description This service de-activates the PCM time slots configured for this FXO channel. #define M1966_PCM_ACTIVATION_CLEAR _IOWR(0xA4,0xDA,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PCM_ACTIVATION_CLEAR, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_PCM_ACTIVATION_CLEAR I/O control identifier for this operation.
PAGE 32
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.14 M1966_CNTRY_NMBR_GET Description Converts a null terminated ASCII string into a country code. This country code can be used in the M1966_CH_INIT IOCTL. #define M1966_CNTRY_NMBR_GET _IOWR(0xA4,0xB5,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_CNTRY_NMBR_GET, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_CNTRY_NMBR_GET I/O control identifier for this operation.
PAGE 33
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.15 M1966_GET_COUNTRY_CONFIG This IOCTL allows an application program to read the current default setting for a particular country using the country code as an input. Description Reads the current default setting for a given country. The country code is passed in via the cnum field of the M1966_CNTRY_STRUCT_t structure. This structure is also used by the driver to return the parameter.
PAGE 34
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.16 M1966_SET_COUNTRY_CONFIG This IOCTL allows application program to write the current default setting for a particular country using the country code as an input. Once written this becomes the new default setting for the country code until the system is rebooted. For persistence change of default country parameter the 73m1966_cntry_tbl.c must be change and rebuilt. Description Write to the current default setting of a given country code.
PAGE 35
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.17 M1966_PHONE_VOLUME_SET Description The gain of both transmit and receive path can be controlled by digital and/or analog means. This IOCTL provides an easy way to set the transmit and receive gain. #define M1966_PHONE_VOLUME_SET _IOWR(0xA4,0xCA,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PHONE_VOLUME_SET, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor.
PAGE 36
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.18 M1966_PERF_RX_OFFSET_CALIB This IOCTL allows an application program to perform receive DC offset calibration on demand while the FXO line is in on-hook state, Description Performs receive offset calibration. #define M1966_PERF_RX_OFFSET_CALIB _IOWR(0xA4, 0xF7, unsigned int) Prototype int ioctl ( int chan_fd, int M1966_PERF_RX_OFFSET_CALIB, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor.
PAGE 37
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.1.19 M1966_CLEAR_RX_OFFSET_REG Description Clears the receive offset measurement register. The receive offset measurement register is used to store the result of receive offset measurement. This IOCTL allows upper layer application to unconditionally set the value in this register to ZERO.
PAGE 38
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.1.20 M1966_SAMPLE_RATE Description Select PCM sample rate. The 1x66 device can operate in one of two sample rates – 8 kHz or 16 kHz sample rate. The device defaults to 8 kHz operation upon startup and can be changed to run at 16 kHz using this ioctl. Notes: Changing of PCM sample rate will affect the followings: 1.
PAGE 39
UG_1x66B_015 6.2 73M1866B/73M1966B Reference Driver User Guide Events and Status Service The driver can be queried for a variety of current status of the FXO line via IOCTLs. Table 2 summarizes these services. Table 2: FXO Line Status Services Events and Status M1966_RNG_GET Description Descriptor FXO line ring status commands. Channel M1966_POL_GET FXO line polarity status commands. Channel M1966_BAT_GET FXO line battery status command. Channel M1966_POH_GET FXO line POH status command.
PAGE 40
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.2.2 M1966_POL_GET Description Gets the current polarity reversal status of the FXO line. The driver maintains this status in its local variable and it is being retrieved by user application using this command.
PAGE 41
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.2.3 M1966_BAT_GET Description Gets the current battery status of the FXO line. The driver maintains this status in its local variable and it is being retrieved by user application using this command. #define M1966_BAT_GET _IOWR(0xA4,0xB6,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_BAT_GET, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_BAT_GET I/O control identifier for this operation.
PAGE 42
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.2.4 M1966_POH_GET Description Gets the current “parallel phone off-hook” status of the FXO line. The driver maintains this status in its local variable and it is being retrieved by user application using this command. #define M1966_POH_GET _IOWR(0xA4,0xB9,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_POH_GET, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor.
PAGE 43
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.2.5 M1966_EVENT_GET Description Returns an event from the FIFO queue. The driver records various events in its internal FIFO queue. Access to this event on this queue by user application is accomplished using this command, and the event will be removed permanently from the queue.
PAGE 44
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.2.6 M1966_ERROR_CODE_GET Description This IOCTL returns the error code of the last IOCTL command. The driver records only the last error code and applicable to device and channel descriptor. #define M1966_ERROR_CODE_GET _IOWR(0xA4,0xB2,unsigned int) Prototype int ioctl ( int dev_fd, int M1966_ERROR_CODE_GET, unsigned long param ); Parameters Data Type Name Description int dev_fd/chan_fd Device or Channel descriptor.
PAGE 45
UG_1x66B_015 6.3 73M1866B/73M1966B Reference Driver User Guide FXO Hook Switch Control Services The configuration and control of the FXO Hook Switch is accomplished by using the IOCTLs summarized in Table 3. Table 3: FXO Hook Switch Control Services Events and Status M1966B_ENNOM_DELAY_TIMER Description Descriptor Allows the developer to tune the EnNom response timer. Channel M1966_ATH1 Issue off-hook in the FXO interface. Channel M1966_ATH0 Issue on-hook in the FXO interface.
PAGE 46
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.3.2 M1966_ATH1 Description Issues the off-hook signal to the FXO interface. #define M1966_ATH1 _IOWR(0xA4,0xA2,unsigned int) Note: The driver provides an option to generate a battery status event upon completion of this off-hook procedure. This option is controlled by the following macro defined in the drv_config_user.h header file.
PAGE 47
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.3.3 M1966_ATH0 Description Issues on-hook in the FXO interface. #define M1966_ATH0 _IOWR(0xA4,0xA1,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_ATH0, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_ATH0 I/O control identifier for this operation. unsigned long param N/A. Return Values Data Type int Rev. 2.7 Description Always returns 0.
PAGE 48
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.3.4 M1966_ATDP Description Performs pulse dialing on the FXO channel. As a pulse dial procedure can take more than a second per digit, it is absolutely essential that this session be carried out transparently in the background without locking up the caller during the process. Therefore, this IOCTL is a non-blocking call and it returns immediately after scheduling the background process to start the pulse dialing.
PAGE 49
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.3.5 M1966_ATDP_CANCEL Description Aborts or cancels an active pulse session requested previously by using the M1966_ATDP IOCTL. The cancelation occurs in the background and, when it is done, the driver sends an M1966_DIAL_ABORTED event.
PAGE 50
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.3.6 M1966_ATDP_PARAM Description This IOCTL is used to modify or read the following default pulse dial parameters: • On hook duration (default = 60 ms) • Off hook duration (default = 40 ms) • Inter-digit duration (default = 1 sec) The command field in the M1966_PULSE_DIAL_PARAM_t structure indicates whether it is a read or a write operation.
PAGE 51
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.3.7 M1966_FLSH_CFG Description This is the configuration of flash-hook timing parameter for the FXO interface. #define M1966_FLSH_CFG _IOWR(0xA4,0xBA,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_FLSH_CFG, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_FLSH_CFG I/O control identifier for this operation. unsigned long param The desired flash duration. Range from 5 to 50 ms, inclusive.
PAGE 52
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.3.9 M1966_SEND_WETTING_PULSE Description Performs hook flashing on the FXO interface for the duration set by param. #define M1966_FLSH_SET _IOWR(0xA4,0xBC,unsigned int) Prototype int ioctl ( int chan_fd, int M1966_SEND_WETTING_PULSE, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_SEND_WETTING_PULSE I/O control identifier for this operation.
PAGE 53
UG_1x66B_015 6.4 73M1866B/73M1966B Reference Driver User Guide Caller-ID Services The following service control how the FXO manages Type 1 Caller-ID. Table 4: Call ID Services Name M1966_ENABLE_CALLER_ID Description Descriptor Enable automatic Caller ID enabling mode. Channel M1966_DISABLE_CALLER_ID Disable automatic Caller ID enabling mode. Channel M1966_ENTER_CID_MODE Manually enter Caller ID mode. Channel M1966_EXIT_CID_MODE Manually exit Caller ID mode. Channel 6.4.
PAGE 54
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.4.2 M1966_DISABLE_CALLER_ID Description Disables the automatic Caller ID processing. By default the driver will start Caller ID mode with an on hook transition. This can be disabled by upper layer application using this service.
PAGE 55
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.4.3 M1966_ENTER_CID_MODE Description Manually enters Caller ID mode regardless of the state of the automatic CID service. #define M1966_ENTER_CID_MODE _IOWR(0xA4, 0xF2, unsigned int) Prototype int ioctl ( int chan_fd, int M1966_ENTER_CID_MODE, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_ENTER_CID_MODE I/O control identifier for this operation. unsigned long param N/A. Channel descriptor.
PAGE 56
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.4.4 M1966_EXIT_CID_MODE Description Exits Caller ID mode. #define M1966_EXIT_CID_MODE _IOWR(0xA4, 0xF2, unsigned int) Prototype int ioctl ( int chan_fd, int M1966_EXIT_CID_MODE, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_EXIT_CID_MODE I/O control identifier for this operation. unsigned long param N/A. Return Values Data Type Description int Always returns 0. 56 Rev.
PAGE 57
UG_1x66B_015 6.5 73M1866B/73M1966B Reference Driver User Guide Ring Detection Services The following services control how the FXO manages Ring Detection. Table 5: Ring Detection Services Name M1966_SET_MIN_INTER_RING_GAP Description Descriptor Set minimum inter-ring timer value. Channel M1966_SET_RING_MIN_FREQ Set min frequency threshold for ring filter. Channel M1966_SET_RING_MAX_FREQ Set max frequency threshold for ring filter. Channel 6.5.
PAGE 58
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.5.2 M1966_SET_RING_MIN_FREQ Description Upon detection of a ring burst the driver will attempt to determine the ring burst frequency. If the ring burst frequency is above the minimum ring frequency and below the maximum frequency then the driver will report an M1966_RING_DETECT event.
PAGE 59
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.5.3 M1966_SET_RING_MAX_FREQ Description Upon detection of a ring burst the driver will attempt to determine the ring burst frequency. If the ring burst frequency is above the minimum ring frequency and below the maximum frequency, then the driver will report an M1966_RING_DETECT event.
PAGE 60
73M1866B/73M1966B Reference Driver User Guide 6.6 UG_1x66B_015 Line State Analysis Services The following services control the FXO line state via line current and line voltage measurements. Table 6 provides the summary of each IOCTL. These IOCTLs can be used for both measuring entities – the line current and line voltage. Table 6: Line State Analysis Services Name Description Descriptor M1966_MEASURE_START Start line measurement. Channel M1966_MEASURE_STOP Stop line measurement.
PAGE 61
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.6.2 M1966_MEASURE_STOP Description Stops an on-going measurement (current or voltage). The param parameter points to a structure that contains the requested stop measuring entity. #define M1966_MEASURE_STOP _IOWR(0xA4, 0xE6, unsigned int) Prototype int ioctl ( int chan_fd, int M1966_MEASURE_STOP, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor.
PAGE 62
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.6.3 M1966_MEASURE_UPDATE Description Reads an IET entry or updates an IET entry based on provided parameters. The param parameter points to a structure that contains the requested action (GET or SET), the measuring entity (current or voltage), the IET table index, and its attributes, if used in the SET operation. For GET operations the IET attributes will be read from the driver.
PAGE 63
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide The following example code illustrates a reading of a line voltage IET table entry. M1966_MEASURE_UPDATE_t read; int ret; read.row = 5; /* read row 5 of voltage IET table */ read.action = M1966_MEASURE_ACTION_GET; /* request for GET operation */ read.
PAGE 64
73M1866B/73M1966B Reference Driver User Guide 6.7 UG_1x66B_015 GPIO Services 6.7.1 M1966_GPIO_CONFIG Description The ioctl is used to configure the GPIO pin. #define M1966_GPIO_CONFIG _IOWR(0xA4, 0xC0, unsigned int) Prototype int ioctl ( int chan_fd, int M1966_GPIO_CONFIG, unsigned long param ); Parameters Data Type int Name chan_fd Description int M1966_GPIO_CONFIG I/O control identifier for this operation. unsigned long param Pointer to M1966_GPIO_CONFIG_t structure. Channel descriptor.
PAGE 65
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.7.3 M1966_GPIO_DATA Description This IOCTL is used to read or write data from and to the GPIO pin. #define M1966_GPIO_DATA _IOWR(0xA4, 0xC2, unsigned int) Prototype int ioctl ( int chan_fd, int M1966_GPIO_DATA, unsigned long param ); Parameters Data Type Name Description int chan_fd Channel descriptor. int M1966_GPIO_DATA I/O control identifier for this operation. unsigned long param Pointer to M1966_GPIO_DATA_t structure.
PAGE 66
73M1866B/73M1966B Reference Driver User Guide 6.8 UG_1x66B_015 Loopback Services 6.8.1 M1966_LOOPBACK Description This IOCTL is used for managing the loopback session – initiating, clearing or retrieving the status of current active loopback session on a given channel. Only one loopback session can be active per channel. For reading the status the loopback “mode” will be returned in the structure M1966_LOOPBACK_t pointed to by the “param” field.
PAGE 67
UG_1x66B_015 6.9 73M1866B/73M1966B Reference Driver User Guide Miscellaneous 6.9.1 M1966_THRESHOLD_OVERRIDE Description Various FXO channel parameters are conveniently grouped and predefined in the country parameter setting as specified in Section 7.2. These parameters are programmed during channel initialization ioctl (M1966_CH_INIT). However, these parameters can be overridden at runtime to fine tune to the desired threshold for the specific installation using this M1966_THRESHOLD_OVERRIDE IOCTL.
PAGE 68
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.9.2 M1966_BTONE_FILTER Description Large amplitude out-of-band tones can be used to measure call duration and to allow remote central office to determine the duration of the call for billing purposes. These tones can saturate or distort the input signal, thus, it is important to be able to reject them. This IOCTL provides the ability to filter out the billing tone.
PAGE 69
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.9.3 M1966_CPROG_MONITOR Description The Call Progress Monitor monitors activities on the line. The audio output contains both transmit and receive data with a configurable level individually can be set using this IOCTL.
PAGE 70
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 6.9.4 M1966_DEBUG_LEVEL_SET Description Sets the driver trace mask to enable or disable run-time trace messages. Multiple trace masks can be ORed together. #define M1966_DEBUG_LEVEL_SET _IOWR(0xA4,0xE1,unsigned int) Prototype int ioctl ( int dev_fd, int M1966_DEBUG_LEVEL_SET, unsigned long param ); Parameters Data Type Name Description int dev_fd Device descriptor. int M1966_DEBUG_LEVEL_SET I/O control identifier for this operation.
PAGE 71
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 6.9.5 M1966_TEST_CODE Description The M1966_TEST_CODE ioctl command can be used as debugging aid during development processed. This mechanism provides a hook for application level developer to interact with the driver’s internal processing. Refer to current source code for handling M1966_TEST_CODE with parameter from 1 to 7 for sample reference.
PAGE 72
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7 Type and Structure Definition Reference This section contains the type definitions, reference of data type and structure used in the 73M1x66B driver. 7.1 M1966_COUNTRY_CODE Description List of country codes use in the M1966_CH_INIT IOCTL.
PAGE 73
UG_1x66B_015 #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define Rev. 2.
PAGE 74
73M1866B/73M1966B Reference Driver User Guide 7.2 UG_1x66B_015 M1966_CNTRY_STRUCT_t Description This structure defines the country default parameters.
PAGE 75
UG_1x66B_015 7.3 73M1866B/73M1966B Reference Driver User Guide M1966_DEBUG_TRACE_MASK Description Trace macros used by the M1966_DEBUG_LEVEL_SET IOCTL. Prototype #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define 7.
PAGE 76
73M1866B/73M1966B Reference Driver User Guide 7.5 UG_1x66B_015 struct txrx_gain Description This structure is used by the M1966_PHONE_VOLUME_SET IOCTL to adjust the volume setting of the speakerphone and microphone. Prototype struct txrx_gain { int tx_gain; int rx_gain; }; Parameters Data Type Name Transmit int tx_gain Transmit level in dBm. Int rx_gain Receive level in dB. 7.6 M1966_PULSE_DIAL_t Description This structure is used by the M1966_ATDP IOCTLs for pulse dialing.
PAGE 77
UG_1x66B_015 7.7 73M1866B/73M1966B Reference Driver User Guide M1966_PULSE_DIAL_PARAM_t Description This structure is used by the M1966_ATDP_PARAM IOCTLs to read or modify the pulse dial parameter. The command field indicates whether it is a read or a write operation.
PAGE 78
73M1866B/73M1966B Reference Driver User Guide 7.9 UG_1x66B_015 M1966_SAMPLE_RATE_SELECTION Description This is the enumerated sample rate selection. It is used by the X ioctl to select the PCM sample rate. Prototype typedef enum { M1966_RATE_SEL_8KHZ = 0, M1966_RATE_SEL_16KHZ = 1 } M1966_SAMPLE_RATE_SELECTION; /* PCM sample rate at 8Khz */ /* PCM sample rate at 16Khz */ Parameters Name M1966_RATE_SEL_8KHZ Value 0 Description M1966_RATE_SEL_16KHZ 1 PCM sample rate at 16 kHz.
PAGE 79
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.10.2 M1966_BTONE_FREQUENCY Description This is the list of tone frequencies that can be filtered out. The user must select the right frequency to effectively filter out the billing tone. Prototype typedef enum { M1966_BTONE_FREQ_12KHZ M1966_BTONE_FREQ_16KHZ } M1966_BTONE_FREQUENCY; = 0, = 1 /* 12KHz (F1) */ /* 16KHz (F2) */ Parameters Name Value Description M1966_BTONE FREQ_12KHZ 0 12 kHz billing tone.
PAGE 80
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7.11 Call Progress Monitor Data Type and Structure 7.11.1 M1966_CPROG_MON_VOLT_REF Description This contains the list of supported voltage reference at the call progress monitor audio output. This is used in the M1966_CPROG_MONITOR IOCTL to select the voltage reference. Prototype typedef enum { M1966_CPROG_MON_VOLT_REG_1_5 = 0, /* 1.
PAGE 81
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.11.3 M1966_CPROG_MONITOR_t Description This structure is used by the M1966_CPROG_MONITOR IOCTL to adjust (or mute) the gain setting of the call progress monitor audio path.
PAGE 82
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7.12 GPIO Related Data Type and Structures 7.12.1 M1966_GPIO_NUMBER Description This is the list of GPIO pin definitions. Prototype typedef enum { M1966_GPIO_NUM_5 = 0x20, M1966_GPIO_NUM_6 = 0x40, M1966_GPIO_NUM_7 = 0x80 } M1966_GPIO_NUMBER; /* GPIO-5 /* GPIO-6 /* GPIO-7 */ */ */ Parameters Name Value Description M1966_GPIO_NUM_5 0x20 GPIO5 – pin 25 of 73M1906B 32-pin QFN. M1966_GPIO_NUM_6 0x40 GPIO6 – pin 32 of 73M1906B 32-pin QFN.
PAGE 83
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.12.3 M1966_GPIO_CONTROL_TYPE Description GPIO control type definitios. Prototype typedef enum { M1966_GPIO_CONTROL_DISABLE = 0, M1966_GPIO_CONTROL_ENABLE = 1 } M1966_GPIO_CONTROL_TYPE; /* disable GPIO /* enable GPIO */ */ Parameters Name Value Description M1966_GPIO_CONTROL_DISABLE 0 Disable GPIO. M1966_GPIO_CONTROL_ENABLE 1 Enable GPIO. 7.12.4 M1966_GPIO_DATA_COMMAND Description GPIO data access command.
PAGE 84
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7.12.5 M1966_GPIO_DATA_TYPE Description GPIO data types – this is the GPIO data returned from the M1966_GPIO_DATA_GET access command, or data to be written to the GPIO port using the M1966_GPIO_DATA_SET access command.
PAGE 85
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.12.7 M1966_GPIO_INTR_POLARITY Description GPIO Interrupt signal transition edge selection. The defines the interrupt source as being either on a rising or a falling edge of the corresponding GPIO pin. If configured as M1966_GPIO_POL_RISING a rising edge will trigger an interrupt from the corresponding GPIO pin. If configured as M1966_GPIO_POL_FALLING a falling edge will trigger an interrupt from the corresponding GPIO pin.
PAGE 86
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7.12.9 M1966_GPIO_DATA_t Description This structure is used by the M1966_GPIO_DATA IOCTLs to read or write GPIO signal from or to the GPIO pin. Prototype typedef struct gpio_data { M1966_GPIO_DATA_COMMAND M1966_GPIO_NUMBER M1966_GPIO_DATA_TYPE } M1966_GPIO_DATA_t; command; gpio; data; /* command */ /* GPIO number */ /* data */ Parameters Data Type Name Description M1966_GPIO_DATA_COMMAND command Read or Write command.
PAGE 87
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.13 Loopback Related Data Type and Structure 7.13.1 M1966_LOOPBACK_COMMAND Description These loopback commands can be used in the M1966_LOOPBACK IOCTL to manage loopback sessions.
PAGE 88
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7.13.3 M1966_LOOPBACK_t Description This is the structure used for managing the loopback with the M1966_LOOPBACK IOCTL. Prototype typedef struct m1966_loopback_struct { M1966_LOOPBACK_COMMAND command; M1966_LOOPBACK_MODE mode; } M1966_LOOPBACK_t; Parameters Name Value Description M1966_LOOPBACK_COMMAND Command Loopback command. M1966_LOOPBACK_MODE type Loopback mode. 7.14 Line Measurement Related Data Types and Structures 7.14.
PAGE 89
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.14.2 M1966_MEASURE_ACTION Description This is the enumerated list of possible request actions that can be performed on Interval and Event Table (IET). See M1966_IET_t for a description of the IET table. Prototype typedef enum { M1966_MEASURE_ACTION_GET = 0, M1966_MEASURE_ACTION_SET = 1, M1966_MEASURE_ACTION_SET = 2 } M1966_MEASURE_ACTION; Parameters Name Value Description M1966_MEASURE_ACTION_GET 0 Read the IET table entry.
PAGE 90
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 7.14.4 M1966_MEASURE_UPDATE_t Description This structure is used by the M1966_MEASURE_UPDATE IOCTL to send the IET table entry parameters for update, or to read its content. The action parameter in the structure indicates the desired operation. The GET operation performs the read function while the SET operation performs write or modify function.
PAGE 91
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 7.14.5 M1966_IET_t Description This Interval and Event Table structure (IET) is internally used by the driver to store threshold parameters for monitoring line current and voltage.
PAGE 92
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 8 Porting to a Specific H/W Platform As stated earlier, it is anticipated that customer will be spending considerable time in this section. This section provides guidelines for porting the device driver to the customer environment. 8.1 Driver Source and Include Files The driver software is written exclusively in the C programming language and consists of the following: Table 7: Driver Source Code Files File Name 73m1966.
PAGE 93
UG_1x66B_015 8.3 73M1866B/73M1966B Reference Driver User Guide Platform Dependent Macros The following macros are used in the driver code (defined in drv_config_user.h). These macros must be defined according to the specific hardware environment and platform. It is expected that the use of the driver will provide these macros workable with their environment.
PAGE 94
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 SPI_WAIT_FOR_READY (status); SPI_CS_SET_HIGH (0); } while(0) /*================================================*/ /*================================================*/ #define M1966_SPI_READ_BYTE(global,byte_ptr) do { int status; SPI_WAIT_FOR_READY (status); SPI_CS_SET_LOW (0); SPI_LL_READ_WRITE (0, 0, byte_ptr, 1); SPI_WAIT_FOR_READY (status); SPI_CS_SET_HIGH (0); } while(0) /*================================================*/ /*==================
PAGE 95
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide 9 Related Documentation The following 73M1x66B documents are available from Teridian Semiconductor Corporation: 73M1866B/73M1966B Data Sheet 73M1866B/73M1966B Demo Board User Manual 73M1866B/73M1966B GUI User Guide 73M1866B/73M1966B Layout Guidelines 73M1x66B Worldwide Design Guide 10 Contact Information For more information about Teridian Semiconductor products or to check the availability of the 73M1866B and 73M1966B, contact us at: 6440 Oak Ca
PAGE 96
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 Appendix A – Country Codes Table 8 provides all the defined countries, their corresponding two-character codes and their indexes.
PAGE 97
UG_1x66B_015 73M1866B/73M1966B Reference Driver User Guide Revision History Revision Date Description 2.0 8/22/2008 First publication. 2.2 12/15/2008 In Section 2.4.1, changed the name of the rcvry_tasklet_rtn tasklet to m1966_pll_recovery_processing(). Replaced the contents of Table 2. In Section 6.1, added four new files (sys_drv_os.c, 73m1966_regs.h, drv_config_user.h and sys_drv_os.h) with descriptions. In Section 6.2, replaced the macros with new macros.
PAGE 98
73M1866B/73M1966B Reference Driver User Guide UG_1x66B_015 2.5.2 8/13/2009 Changed all instances of M1966_FXO_EVENT to M1966_FXO_EVENT_t. Changed all instances of Device ID to Channel ID in the M1966_FXO_EVENT_t structure. Added the M1966_DIAL_COMPLETE, M1966_DIAL ABORTED, and M1966_SYNC_RECOVERED events. Changed Device descriptor to Channel descriptor for all initialization IOCTLs.