User guide

ManualsBrandsMaxim Integrated ManualsHardware73M1822/73M1922 Modem API

Simplifying System Integration

73M1822/73M1922

Modem API User Guide

December 23, 2009

Rev. 1.0

UG_1x22_055

Summary of content (37 pages)

PAGE 1
Simplifying System IntegrationTM 73M1822/73M1922 Modem API User Guide December 23, 2009 Rev. 1.
PAGE 2
73M1822/73M1922 Modem API User Guide UG_1x22_055 © 2009 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. All other trademarks are the property of their respective owners.
PAGE 3
UG_1x22_055 73M1822/73M1922 Modem API User Guide Table of Contents 1 2 3 Introduction ................................................................................................................................... 5 1.1 Overview ................................................................................................................................. 6 1.2 Conventions Used in this Guide ............................................................................................... 6 1.
PAGE 4
73M1822/73M1922 Modem API User Guide UG_1x22_055 Figures Figure 1: Driver API ................................................................................................................................. 5 Tables Table 1: API Overview ............................................................................................................................. 7 Table 2: Structure Overview...................................................................................................................
PAGE 5
UG_1x22_055 73M1822/73M1922 Modem API User Guide 1 Introduction This document describes the application programming interface (API) of the Teridian 73M1x22 Modem API. The API is defined as a simplified functional interface that allows an application program written in ® “C” language to communicate with the driver without going through complicate and cumbersome Linux driver IOCTL.
PAGE 6
73M1822/73M1922 Modem API User Guide 1.1 UG_1x22_055 Overview The Modem API is a user-friendly programming conduit used to access and manage the modem device/channel via the Reference Driver. This section describes the programming flow and how the application program can be implemented using the Modem APIs. First, the concept of device versus channel, the Teridian 73M1x22 Control module supports multiple modem channels. The application layer communicates with the driver using this channel descriptor.
PAGE 7
UG_1x22_055 2 73M1822/73M1922 Modem API User Guide API Descriptions This section contains the detail description of each API. Table 1 provides a summary of the APIs. Table 1: API Overview IOCTL Name Description M1X22_MdmApiInit API subsystem initialization. M1X22_MdmApiRelease API subsystem release or termination. M1X22_OpenDevice Open device of event reporting. M1X22_CloseDevice Close an opened device. M1X22_OpenChannel Open channel for operation.
PAGE 8
73M1822/73M1922 Modem API User Guide 2.1 UG_1x22_055 M1X22_MdmApiInit Description This API allocates and initializes required internal data structures; make necessary preparation before other API members can be invoked. The M1X22_MdmApiInit() must be called once during application program’s initialization, or prior to accessing other API members. Upon exiting of the application program a reversed operation must be performed to release resources using M1X22_MdmApiRelease.
PAGE 9
UG_1x22_055 2.3 73M1822/73M1922 Modem API User Guide M1X22_OpenDevice Description This API performs the low level opening of the device descriptor. By default, the device descriptor name is known as “/dev/tsc_1x22_ctl_device”; however, since this is configurable during driver installation, a different device descriptor name may be used. Refer to driver configuration and installation more detail.
PAGE 10
73M1822/73M1922 Modem API User Guide 2.4 UG_1x22_055 M1X22_CloseDevice Description This API performs the low level closing of the device handle. It should be called before exiting application program to release all resource associated with the open device. Closing this device will automatically force the closing of any opened channel handles.
PAGE 11
UG_1x22_055 2.6 73M1822/73M1922 Modem API User Guide M1X22_CloseChannel Description This API performs the low level closing of the channel handle. It should be called before exiting application program, or when the channel is no longer needed, to release all resources associated with the open channel. Prototype M1X22_RET M1X22_CloseChannel (M1X22_HANDLE chanHandle); Parameters Data Type Name Description M1X22_HANDLE chanHandle Channel handle obtained from open channel.
PAGE 12
73M1822/73M1922 Modem API User Guide 2.8 UG_1x22_055 M1X22_HookSwitch Description Perform on/off-hook on the channel. Prototype M1X22_RET M1X22_HookSwitch ( M1X22_HANDLE channel, M1X22_HOOK_SWITCH hookSwitch ); Parameters Data Type Name Description M1X22_HANDLE channel Channel handle from open channel. M1X22_HOOK_SWITCH hookSwitch Type of hook switch requested. Return Values Data Type M1X22_RET 2.9 Description M1X22_SUCCESS – Successfully performed hook switch. M1X22_FAILED – Failure.
PAGE 13
UG_1x22_055 73M1822/73M1922 Modem API User Guide 2.10 M1X22_HWRegisterRead Description Perform H/W register reading from the 73M1x22 device that carries the channel. This API is not recommended for use in normal operation but only for diagnostic or testing purpose. Prototype M1X22_RET M1X22_HWRegisterRead ( M1X22_HANDLE channel, M1X22_REG_TYPE register, char *pRetData ); Parameters Data Type M1X22_HANDLE Name channel Description M1X22_REG_TYPE register 1x22 register.
PAGE 14
73M1822/73M1922 Modem API User Guide UG_1x22_055 2.12 M1X22_HWRegisterWrite Description Perform H/W register writing to the 73M1x22 device that carries the channel. This API is not recommended for use in normal operation but only for diagnostic or testing purpose. Prototype M1X22_RET M1X22_HWRegisterWrite ( M1X22_REG_TYPE register, char value ); Parameters Data Type M1X22_HANDLE Name channel Description Channel handle from open channel. M1X22_REG_TYPE register 1x22 Register.
PAGE 15
UG_1x22_055 73M1822/73M1922 Modem API User Guide 2.14 M1X22_SetPhoneVolume Description Set the speaker phone and microphone volume. This API sets transmit and receive dB gain of the channel. Prototype M1X22_RET M1X22_SetPhoneVolume ( M1X22_HANDLE chanHandle, int txVolumedB, int rxVolumedB ); Parameters Data Type M1X22_HANDLE Name chanHandle Description int txVolumedB Transmit direction in dB. int rxVolumedB Receive direction in dB. Channel handle obtains from open channel.
PAGE 16
73M1822/73M1922 Modem API User Guide UG_1x22_055 2.16 M1X22_GetFileDescriptor Description To provide full flexibility to the driver access, this API can be called by an application program to obtain the file descriptor for a given device or channel handle. With this returned file descriptor, the user has direct access to the driver via its native IOCTL as described in the 73M1822/73M1922 Control Module User Guide.
PAGE 17
UG_1x22_055 73M1822/73M1922 Modem API User Guide 2.18 M1X22_UpdateCurrentIET Description Perform the line current IET table update. Prototype int M1X22_UpdateCurrentIET ( M1X22_HANDLE channel, unsigned int ietIndex, M1X22_IET_t *pIET ); Parameters Data Type M1X22_HANDLE Name channel Description Channel handle obtained from open channel. unsigned int ietIndex IET entry index – row number (0 – 9). M1X22_IET_t *pIET Pointer to an input structure M1X22_IET_t.
PAGE 18
73M1822/73M1922 Modem API User Guide UG_1x22_055 2.20 M1X22_GetVoltageIET Description Read the line voltage IET table entry. Prototype int M1X22_GetVoltageIET ( M1X22_HANDLE channel, unsigned int ietIndex, M1X22_IET_t *pIET ); Parameters Data Type M1X22_HANDLE Name channel Description Channel handle obtained from open channel. unsigned int ietIndex IET entry index – row number (0 – 9). M1X22_IET_t *pIET Pointer to an output structure M1X22_IET_t.
PAGE 19
UG_1x22_055 73M1822/73M1922 Modem API User Guide 2.22 M1X22_ClearVoltageIET Description Delete the line voltage IET table entry. Prototype int M1X22_ClearVoltageIET ( M1X22_HANDLE channel, unsigned int ietIndex); Parameters Data Type Name Description M1X22_HANDLE channel Channel handle obtained from open channel. unsigned int ietIndex IET entry index – row number (0 – 9). Return Values Data Type Description M1X22_RET M1X22_SUCCESS – Successfully clear the IET entry. M1X22_FAILED – Failure. 2.
PAGE 20
73M1822/73M1922 Modem API User Guide UG_1x22_055 2.24 M1X22_StartMeasureVoltage Description Start the line voltage measurement process. Prototype int M1X22_StartMeasureVoltage ( M1X22_HANDLE channel, unsigned int sampleTime, unsigned int averageSampleCount ); Parameters Data Type M1X22_HANDLE Name channel Description unsigned int sampleTime Time interval between two consecutive samples. unsigned int averageSampleCount Sample count for average calculation.
PAGE 21
UG_1x22_055 73M1822/73M1922 Modem API User Guide 2.26 M1X22_StopMeasureVoltage Description Stop the line voltage measurement. Prototype int M1X22_StopMeasureVoltage ( M1X22_HANDLE channel, unsigned int sampleTime, unsigned int averageSampleCount ); Parameters Data Type M1X22_HANDLE Name channel Description unsigned int sampleTime Time interval between two consecutive samples. unsigned int averageSampleCount Sample count for average calculation. Channel handle obtained from open channel.
PAGE 22
73M1822/73M1922 Modem API User Guide UG_1x22_055 2.27 M1X22_SetRingCadence Description Set the ring cadence parameter for ring qualification process. The driver can be programmed to filter and qualify incoming ring by discarding spurious signals that can be caused by line noises or distortions.
PAGE 23
UG_1x22_055 73M1822/73M1922 Modem API User Guide 3 Structure Reference This section contains the detail description of the data structure used in this API subsystem. Table 2 contains the summary of the reference structure. Table 2: Structure Overview Name Description M1X22_HANDLE Device or Channel handle. M1X22_CHAN_INIT Channel Init structure. 3.
PAGE 24
73M1822/73M1922 Modem API User Guide 3.2 UG_1x22_055 M1X22_CHAN_INIT Description Channel initialization structure. This structure contains mainly the country code. The M1X22_InitChannel API passes the pointer to this data structure to configure the channel to operate in a specific region. Refer to M1X22_COUNTRY_CODE for the list of countries supported.
PAGE 25
UG_1x22_055 73M1822/73M1922 Modem API User Guide 4 Enumerator Reference This section contains the detail description of the enumerated data reference used in this API subsystem. Table 3 contains the summary of the enumerated data reference. Table 3: Enumerator Overview Name M1X22_RET Description M1X22_EVENT_ID Event identification. M1X22_COUNTRY_CODE List of country code supported. M1X22_HOOK_SWITCH On and off hook. M1X22_REG_TYPE List of 1x22 device H/W register.
PAGE 26
73M1822/73M1922 Modem API User Guide 4.2 UG_1x22_055 M1X22_EVENT_ID Description List of event identification supported by the API subsystem.
PAGE 27
UG_1x22_055 4.3 73M1822/73M1922 Modem API User Guide M1X22_COUNTRY_CODE Description List of country codes supported by the API subsystem.
PAGE 28
73M1822/73M1922 Modem API User Guide M1X22_CNTRY_CODE_NG M1X22_CNTRY_CODE_NO M1X22_CNTRY_CODE_OM M1X22_CNTRY_CODE_PK M1X22_CNTRY_CODE_PR M1X22_CNTRY_CODE_PH M1X22_CNTRY_CODE_PL M1X22_CNTRY_CODE_PT M1X22_CNTRY_CODE_RO M1X22_CNTRY_CODE_RU M1X22_CNTRY_CODE_SA M1X22_CNTRY_CODE_SG M1X22_CNTRY_CODE_SK M1X22_CNTRY_CODE_SI M1X22_CNTRY_CODE_ZA M1X22_CNTRY_CODE_KR M1X22_CNTRY_CODE_ES M1X22_CNTRY_CODE_SE M1X22_CNTRY_CODE_CH M1X22_CNTRY_CODE_SY M1X22_CNTRY_CODE_TW M1X22_CNTRY_CODE_TH M1X22_CNTRY_CODE_AE M1X22_CNTRY_COD
PAGE 29
UG_1x22_055 4.4 73M1822/73M1922 Modem API User Guide M1X22_HOOK_SWITCH Description Hook switch command for on-hook and off-hook. Prototype /* ************************************************************************** ** Hook switch *************************************************************************/ typedef enum { M1X22_ON_HOOK = 0, M1X22_OFF_HOOK = 1, } M1X22_HOOK_SWITCH; Name M1X22_ON_HOOK Value Ox00 On hook. M1X22_OFF_HOOK 0x01 Off hook. Rev. 1.
PAGE 30
73M1822/73M1922 Modem API User Guide 4.5 UG_1x22_055 M1X22_REG_TYPE Description List of 1x22 device register type. Note: Register 0x00 and 0x11 are not available. Reading from or writing to these registers will not have any effect.
PAGE 31
UG_1x22_055 73M1822/73M1922 Modem API User Guide Parameters Name Value Description M1X22_REG_0x00 Ox00 Register 0x00 M1X22_REG_0x01 0x01 Register 0x01 M1X22_REG_0x02 0x02 Register 0x02 M1X22_REG_0x03 0x03 Register 0x03 M1X22_REG_0x04 0x04 Register 0x04 M1X22_REG_0x05 0x05 Register 0x05 M1X22_REG_0x06 0x06 Register 0x06 M1X22_REG_0x07 0x07 Register 0x07 M1X22_REG_0x08 0x08 Register 0x08 M1X22_REG_0x09 0x09 Register 0x09 M1X22_REG_0x0A 0x0A Register 0x0A M1X22_REG_0x0B 0
PAGE 32
73M1822/73M1922 Modem API User Guide 4.6 UG_1x22_055 M1X22_DEBUG_TRACE_MASK Description Defines all debug trace mask.
PAGE 33
UG_1x22_055 73M1822/73M1922 Modem API User Guide 5 Sample Application This section illustrates how an application can be implemented using the Modem APIs. The sample program is a typical telephony application that automatically answers the call when a ring burst is detected. This is accomplished by simply going off-hook. Note: This sample program will definitely not compile and is not a complete application.
PAGE 34
73M1822/73M1922 Modem API User Guide UG_1x22_055 M1X22_RET M1X22_MdmApiRelease (void); Return (0); } /* ***************************************************************************** *********************** * FUNCTION NAME: * fxoEventCallback * * DESCRIPTION: * This is the event callback function. It is invoked by the API * subsystem when an event occurs. Currently, this callback function * only handles the RING start event. It takes the line off-hook when * the ring burst is detected.
PAGE 35
UG_1x22_055 printf("\n %d(ms)\n",data1,data2); break; 73M1822/73M1922 Modem API User Guide Frequency: %d(hz), Duration: case M1X22_EVENT_POLARITY_REV: printf("\nPOLARITY_CHANGE(%d)\n\r",channelId); break; case M1X22_EVENT_BATT_FEED: printf("\nBATTERY_FEEDED(%d)\n\r",channelId); break; case M1X22_EVENT_BATT_DROP: printf("\nBATTERY_DROPPED(%d)\n\r",channelId); break; case M1X22_EVENT_APOH: printf("\nAPOH(%d)\n\r",channelId); break; case M1X22_EVENT_NOPOH: printf("\nNOPOH(%d)\n\r",channelId); break; case M1X
PAGE 36
73M1822/73M1922 Modem API User Guide UG_1x22_055 6 Related Documentation The following 73M1x22 documents are available from Teridian Semiconductor Corporation: 73M1822/73M1922 Data Sheet 73M1822/73M1922 Layout Guidelines 73M1x22 Worldwide Design Guide 73M1822/73M1922 Control Module User Guide 73M1822/73M1922 Hardware Module for SMDK412 User Guide 73M1822/73M1922 Modem API User Guide 73M1822/73M1922 Modem CTL Application User Guide 73M1822/73M1922 MicroDAA Software Architecture 7 Contact Information For m
PAGE 37
UG_1x22_055 73M1822/73M1922 Modem API User Guide Revision History Revision Date Description 1.0 12/23/2009 First publication. Rev. 1.