Intel EP80579 Software for IP Telephony Applications on Intel QuickAssist Technology Linux* Device Driver API Reference Manual

Transcription

1 Intel EP80579 Software for IP Telephony Applications on Intel QuickAssist Technology Linux* Device Driver API Reference Manual Automatically generated from sources, November 19, Based on Intel IP Telephony Applications API Version 1.2 Reference Number: , Revision -002

2 INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTELS TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications. Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked ''reserved'' or ''undefined.'' Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information. The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order. Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling , or by visiting Intel's Web Site. Any software source code reprinted in this document is furnished under a software license and may only be used or copied in accordance with the terms of that license. This document contains information on products in the design phase of development. Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. See for details. Code Names are only for use by Intel to identify products, platforms, programs, services, etc. (''products'') in development by Intel that have not been made commercially available to the public, i.e., announced, launched or shipped. They are never to be used as ''commercial'' names for products. Also, they are not intended to function as trademarks. BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino logo, Core Inside, FlashFile, i960, InstantIP, Intel, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, Intel Core, Intel Inside, Intel Inside logo, Intel. Leap ahead., Intel. Leap ahead. logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Viiv, Intel vpro, Intel XScale, Itanium, Itanium Inside, MCS, MMX, Oplus, OverDrive, PDCharm, Pentium, Pentium Inside, skoool, Sound Mark, The Journey Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries. *Other names and brands may be claimed as the property of others. Copyright Intel Corporation All Rights Reserved. Reference Number: , Revision -002

3 Revision History Date Revision Description Documents version 1.2 of the Intel IP Nov. 19, Telephony Applications API. Updated SRTP Acceleration Driver API. Sept. 11, First released version of this document Documents version 1.1 of the API. Reference Number: , Revision -002

4 Table of Contents 1 Analog FXO/FXS device driver API Detailed Description Data Structures Defines Typedefs Data Structure Documentation icp_analogdrv_init_s Struct Reference icp_analogdrv_event_s Struct Reference icp_analogdrv_pcm_config_s Struct Reference icp_analogdrv_gen_reg_s Struct Reference icp_analogdrv_tone_s Struct Reference Define Documentation Typedef Documentation Framer device driver API Detailed Description Data Structures Defines Typedefs Functions Data Structure Documentation icp_framerdrv_stats_s Struct Reference icp_framerdrv_event_s Struct Reference Define Documentation Typedef Documentation Function Documentation HSS data device driver API Detailed Description Data Structures Defines Typedefs Enumerations Data Structure Documentation icp_hssdatadrv_channeladd_s Struct Reference Define Documentation Typedef Documentation Enumeration Type Documentation Definitions common to the HSS voice and HSS data drivers Detailed Description Data Structures Defines Typedefs Enumerations Data Structure Documentation icp_hssdrv_portup_s Struct Reference icp_hssdrv_timeslot_map_s Struct Reference Define Documentation Typedef Documentation Enumeration Type Documentation HSS voice device driver API Detailed Description Data Structures...54 Reference Number: , Revision -002 i

5 Table of Contents 5 HSS voice device driver API 5.3 Defines Typedefs Data Structure Documentation icp_hssvoicedrv_channeladd_s Struct Reference icp_hssvoicedrv_channelbypass_s Struct Reference Define Documentation Typedef Documentation TDM Setup Driver API Detailed Description Defines Define Documentation TDM Setup Driver Port Reservation APIs Detailed Description Functions Function Documentation SRTP Acceleration Driver API Detailed Description Data Structures Defines Typedefs Enumerations Data Structure Documentation srtp_acc_ctx_s Struct Reference srtp_acc_packet_s Struct Reference srtp_acc_rand_num_s Struct Reference Define Documentation Typedef Documentation Enumeration Type Documentation...73 Reference Number: , Revision -002 ii

6 1 Analog FXO/FXS device driver API 1.1 Detailed Description Public API for the analog FXO/FXS device driver. The Analog FXS/FXO Driver is a Linux Character Device Driver. It presents a Linux user space interface to the client. This Analog FXS/FXO Driver is responsible for managing the SLIC/CODEC (FXS) devices and the DAA (FXO) devices via the SPI interface. This API defines an ioctl interface to the analog FXO/FXS device driver. It provides an interface that allows the client to send commands to the FXS/FXO devices e.g. ring phone to a SLIC/CODEC. It also provides a mechanism to report device events to the client e.g. phone gone off hook from a SLIC/CODEC. The driver implements the following character driver methods that can be used in user space by the client to access the driver: open() - Initializes event queuing and binds interrupts to the FXS/FXO device. release() - de-allocates all resources. ioctl() - Used by the client to pass commands to the FXS/FXO devices. read() - Used by the client to get any single event from the driver that has been generated by the FXS/FXO device. Blocking and non blocking modes are supported. The user buffer returned by the read() method is of the format icp_analogdrv_event_t and specifies the event ID and line ID. By default the driver operates in blocking mode. Calls to read() block until an event has been delivered from the external device, the icp_analogdrv_event_t specifies the event ID and line ID. When configured for non blocking mode (O_NONBLOCK), calls to read() immediately return the next available event. If there are no events available it returns 0. For all communication with FXS/FXO devices, the client is required to specify the analog line ID. The line ID maps to a specific slot, board, chip and port on the reference platform voice mezzanine cards. The supported voice card consists of one FXO port and four FXS ports. Stacking of boards in slots is not supported, i.e., only one board per slot is supported. The line mapping is as follows. Line 0 -> Slot 0 FXO Line 1 -> Slot 0 FXS 0 Line 2 -> Slot 0 FXS 1 Line 3 -> Slot 0 FXS 2 Line 4 -> Slot 0 FXS 3 Line 5 -> Slot 1 FXO Line 6 -> Slot 1 FXS 0 Line 7 -> Slot 1 FXS 1 Line 8 -> Slot 1 FXS 2 Line 9 -> Slot 1 FXS 3 Reference Number: , Revision

7 1.1 Detailed Description Line 10 -> Slot 2 FXO Line 11 -> Slot 2 FXS 0 Line 12 -> Slot 2 FXS 1 Line 13 -> Slot 2 FXS 2 Line 14 -> Slot 2 FXS 3 NOTE: Stacking is not supported so there is only one card per slot. The client can use ioctl in order to configure the Analog FXS/FXO Driver via /dev/analog-fxo-fxs, once the character device file has been successfully opened. Note: The TDM System Initialization Driver should be loaded and initialized before this driver. 1.2 Data Structures struct icp_analogdrv_init_s Slot and predefined geo configuration. struct icp_analogdrv_event_s Event data structure. struct icp_analogdrv_pcm_config_s Pulse Code Modulation (PCM) configuration data for an FXO/FXS line. struct icp_analogdrv_gen_reg_s Register write/read parameter structure. struct icp_analogdrv_tone_s Tone generation configuration for a line. 1.3 Defines #define ICP_ANALOGDRV_IOC_MAGIC Seed for ioctl commands. #define ICP_ANALOGDRV_INIT ioctl command to initialize the voice module in a particular slot on the Customer Reference Board. #define ICP_ANALOGDRV_RING_ON ioctl command for an FXS device to start ringing. #define ICP_ANALOGDRV_RING_OFF ioctl command for an FXS device to stop ringing. #define ICP_ANALOGDRV_HOOKSTATE_GET ioctl command for an FXS device to get the on/off hook state. #define ICP_ANALOGDRV_PCM_CONFIG_SET ioctl command for an FXS or FXO device to configure the Pulse Code Modulation characteristics of a line. #define ICP_ANALOGDRV_PCM_CONFIG_GET ioctl command for an FXS or FXO device to get the Pulse Code Modulation configuration of a line. #define ICP_ANALOGDRV_LOOPBACK_ENABLE ioctl command for an FXS or FXO device to enable loopback mode on the device. #define ICP_ANALOGDRV_LOOPBACK_DISABLE ioctl command for an FXS or FXO device to disable loopback mode on the device. #define ICP_ANALOGDRV_LOOPBACK_GET ioctl command for an FXS or FXO device to query the loopback mode on the device. #define ICP_ANALOGDRV_DEVICE_INFO ioctl command to get the FXS/FXO device information. #define ICP_ANALOGDRV_DEVICE_PRESENT Reference Number: , Revision

8 1.3 Defines ioctl command for an FXS or FXO device to verify that device is present and communicating normally. #define ICP_ANALOGDRV_WRITE_REG ioctl command for an FXS or FXO device to write a value to a device register to perform device specific commands. #define ICP_ANALOGDRV_READ_REG ioctl command for an FXS or FXO device to read a value from a device register. #define ICP_ANALOGDRV_ON_HOOK ioctl command for an FXO device to indicate a change in hook status to on hook. #define ICP_ANALOGDRV_OFF_HOOK ioctl command for an FXO device to indicate a change in hook status to off hook. #define ICP_ANALOGDRV_TONE_ON ioctl command for an FXS device to start transmission of a tone on the line. #define ICP_ANALOGDRV_TONE_OFF ioctl command for an FXS device to stop transmission of a tone on the line. #define ICP_ANALOG_DTMF_0 DTMF '0' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_1 DTMF '1' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_2 DTMF '2' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_3 DTMF '3' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_4 DTMF '4' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_5 DTMF '5' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_6 DTMF '6' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_7 DTMF '7' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_8 DTMF '8' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_9 DTMF '9' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_HASH DTMF '#' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_STAR DTMF '*' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_A DTMF 'A' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_B DTMF 'B' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_C DTMF 'C' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_D DTMF 'D' tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_DIAL DTMF dial tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_BUSY DTMF busy tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_RINGBACK DTMF ringback tone that can be generated on the line by an FXS device. #define ICP_ANALOG_DTMF_CALL_WAITING DTMF call waiting tone that can be generated on the line by an FXS device. #define ICP_ANALOGDRV_EVENT_ON_HOOK Reference Number: , Revision

9 1.4 Typedefs Event ID representing the on hook event/notification that can be generated by an FXS device. #define ICP_ANALOGDRV_EVENT_OFF_HOOK Event ID representing the off hook event/notification that can be generated by an FXS device. #define ICP_ANALOGDRV_EVENT_RING_ON Event ID representing the ring on event/notification that can be generated by an FXO device. #define ICP_ANALOGDRV_EVENT_RING_OFF Event ID representing the ring off event/notification that can be generated by an FXO device. #define ICP_ANALOGDRV_EVENT_POL_REV Event ID representing the polarity reversal notification that can be generated by an FXO device. 1.4 Typedefs typedef icp_analogdrv_init_s icp_analogdrv_init_t Slot and predefined geo configuration. typedef icp_analogdrv_event_s icp_analogdrv_event_t Event data structure. typedef icp_analogdrv_pcm_config_s icp_analogdrv_pcm_config_t Pulse Code Modulation (PCM) configuration data for an FXO/FXS line. typedef icp_analogdrv_gen_reg_s icp_analogdrv_gen_reg_t Register write/read parameter structure. typedef icp_analogdrv_tone_s icp_analogdrv_tone_t Tone generation configuration for a line. 1.5 Data Structure Documentation icp_analogdrv_init_s Struct Reference Detailed Description Slot and predefined geo configuration. This structure contains the slot and the geo configuration. Parameter to the ICP_ANALOGDRV_INIT ioctl(). None Data Fields unsigned int slot Slot on the Customer Reference Board that the voice module is plugged into. unsigned int geo_config Represents the geo configuration selected at init time. unsigned int clk_speed Sets the speed of the clock for the PCM link. Reference Number: , Revision

10 1.5.1 icp_analogdrv_init_s Struct Reference Field Documentation unsigned int icp_analogdrv_init_s::slot Slot on the Customer Reference Board that the voice module is plugged into. This range for this value is 0-2. unsigned int icp_analogdrv_init_s::geo_config Represents the geo configuration selected at init time. Currently three geos are defined, a US FCC configuration (0) an EU TBR21 configuration (1) and a Japanese configuration (2). These configurations can subsequently be altered dynamically by writing directly to the external FXO/FXS chip registers using the ICP_ANALOGDRV_WRITE_REG ioctl. unsigned int icp_analogdrv_init_s::clk_speed Sets the speed of the clock for the PCM link. This setting dictates the number of time slots available on the link. The range for this value is MHz 1-8 MHz icp_analogdrv_event_s Struct Reference Detailed Description Event data structure. Contains the data for the event that is returned in the read() method. It indicates an event type and the line that generated the event. Format of the user buffer returned from a read() call. None Data Fields unsigned int eventtype Event type as specified by the ICP_ANALOG_EVENT_* defines. unsigned int lineid Line to which the event applies Field Documentation unsigned int icp_analogdrv_event_s::eventtype Event type as specified by the ICP_ANALOG_EVENT_* defines. unsigned int icp_analogdrv_event_s::lineid Line to which the event applies. Reference Number: , Revision

11 1.5.2 icp_analogdrv_event_s Struct Reference icp_analogdrv_pcm_config_s Struct Reference Detailed Description Pulse Code Modulation (PCM) configuration data for an FXO/FXS line. This structure contains the data needed to configure an FXO/FXS line. Set/get parameter for the ICP_ANALOGDRV_PCM_CONFIG_SET, ICP_ANALOGDRV_PCM_CONFIG_GET ioctl()s. None Data Fields unsigned int lineid Line to be configured. int pcm_format PCM format that should be used. int pcm_width PCM width, it can be set to 8 or 16 bits. int pcm_samp_freq PCM sampling frequency. int pcm_start_offset The first bit of PCM data is found at this specified offset from the frame pulse Field Documentation unsigned int icp_analogdrv_pcm_config_s::lineid Line to be configured. int icp_analogdrv_pcm_config_s::pcm_format PCM format that should be used. It can be set to Mu-Law =0, A-Law =1 or Linear =2. int icp_analogdrv_pcm_config_s::pcm_width PCM width, it can be set to 8 or 16 bits. int icp_analogdrv_pcm_config_s::pcm_samp_freq PCM sampling frequency. It can be set to 8 or 16 (KHz). int icp_analogdrv_pcm_config_s::pcm_start_offset The first bit of PCM data is found at this specified offset from the frame pulse. This offset represents the number of clock cycles between the frame pulse and the first bit of PCM data. Each bit of data is transmitted over one clock cycle so an offset of 1 PCM timeslot implies the user provides an offset value of 8 clock cycles. Reference Number: , Revision

12 1.5.3 icp_analogdrv_pcm_config_s Struct Reference icp_analogdrv_gen_reg_s Struct Reference Detailed Description Register write/read parameter structure. This structure contains the definition of the parameter for reading/writing value to a register. Read/Writing to an external FXO/FXS chip register is done using the ioctl commands ICP_ANALOGDRV_READ_REG and ICP_ANALOGDRV_WRITE_REG. Set/get parameter for the ICP_ANALOGDRV_WRITE_REG, ICP_ANALOGDRV_READ_REG ioctl()s. None Data Fields unsigned int lineid Line on which to generate the tone. int reg Register that the data should be read or written to. uint8_t data Data to be read/written in the register Field Documentation unsigned int icp_analogdrv_gen_reg_s::lineid Line on which to generate the tone. int icp_analogdrv_gen_reg_s::reg Register that the data should be read or written to. uint8_t icp_analogdrv_gen_reg_s::data Data to be read/written in the register icp_analogdrv_tone_s Struct Reference Detailed Description Tone generation configuration for a line. This structure contains the configuration used to generate a tone on an FXS line using the ioctl command ICP_ANALOGDRV_TONE_ON. Set parameter for the ICP_ANALOGDRV_TONE_ON ioctl(). None Reference Number: , Revision

13 1.5.5 icp_analogdrv_tone_s Struct Reference Data Fields unsigned int lineid FXS line on which to generate the tone. unsigned int tone The tone type as specified by the ICP_ANALOG_DTMF_* defines. unsigned int tone_dir The direction to apply the tone on Field Documentation unsigned int icp_analogdrv_tone_s::lineid FXS line on which to generate the tone. unsigned int icp_analogdrv_tone_s::tone The tone type as specified by the ICP_ANALOG_DTMF_* defines. unsigned int icp_analogdrv_tone_s::tone_dir The direction to apply the tone on. 0 - applies the tone in the forward direction. 1 - applies the tone in the reverse direction. 2 - applies the tone in both directions. 1.6 Define Documentation #define ICP_ANALOGDRV_IOC_MAGIC Seed for ioctl commands. #define ICP_ANALOGDRV_INIT ioctl command to initialize the voice module in a particular slot on the Customer Reference Board. The parameter is a pointer to a data structure of type icp_analogdrv_init_s. #define ICP_ANALOGDRV_RING_ON ioctl command for an FXS device to start ringing. The ioctl arg indicates the line to enable ringing on. #define ICP_ANALOGDRV_RING_OFF ioctl command for an FXS device to stop ringing. The ioctl arg indicates the line to disable ringing on. #define ICP_ANALOGDRV_HOOKSTATE_GET ioctl command for an FXS device to get the on/off hook state. The ioctl arg indicates the line to get the state from. The returned value is the Hook state, on hook (0) or off hook (1). Reference Number: , Revision

14 1.6 Define Documentation #define ICP_ANALOGDRV_PCM_CONFIG_SET ioctl command for an FXS or FXO device to configure the Pulse Code Modulation characteristics of a line. The ioctl arg is a pointer to a struct of type icp_analogdrv_pcm_config_s. #define ICP_ANALOGDRV_PCM_CONFIG_GET ioctl command for an FXS or FXO device to get the Pulse Code Modulation configuration of a line. The ioctl arg is a pointer to a struct of type icp_analogdrv_pcm_config_s. The data fields are set by the ioctl call. #define ICP_ANALOGDRV_LOOPBACK_ENABLE ioctl command for an FXS or FXO device to enable loopback mode on the device. If set PCM data is looped back to the HSS client. The ioctl arg indicates the line to enable loopback on. #define ICP_ANALOGDRV_LOOPBACK_DISABLE ioctl command for an FXS or FXO device to disable loopback mode on the device. The ioctl arg indicates the line to disable loopback on. #define ICP_ANALOGDRV_LOOPBACK_GET ioctl command for an FXS or FXO device to query the loopback mode on the device. The ioctl arg indicates the line to query. The returned value is the loopback mode, disabled (0) or enabled (1). #define ICP_ANALOGDRV_DEVICE_INFO ioctl command to get the FXS/FXO device information. The ioctl arg indicates the lineid to get the device information for. The returned value is the device type, where 0=Si3050, 1=Si3210, 2=Si3216, 3=Si3220. #define ICP_ANALOGDRV_DEVICE_PRESENT ioctl command for an FXS or FXO device to verify that device is present and communicating normally. The returned value is the status of communication where (0) means that there is normal communication or (1) means that communication with the chip is not possible. #define ICP_ANALOGDRV_WRITE_REG ioctl command for an FXS or FXO device to write a value to a device register to perform device specific commands. The parameter is a pointer to an icp_analogdrv_gen_reg_t. #define ICP_ANALOGDRV_READ_REG ioctl command for an FXS or FXO device to read a value from a device register. The parameter is a pointer to an icp_analogdrv_gen_reg_t with the line ID and register values set. On return the data is set to the value read from the device register. #define ICP_ANALOGDRV_ON_HOOK ioctl command for an FXO device to indicate a change in hook status to on hook. Reference Number: , Revision

15 1.6 Define Documentation The ioctl arg indicates the line on which to change the hook status. #define ICP_ANALOGDRV_OFF_HOOK ioctl command for an FXO device to indicate a change in hook status to off hook. The ioctl arg indicates the line on which to change the hook status. #define ICP_ANALOGDRV_TONE_ON ioctl command for an FXS device to start transmission of a tone on the line. The ioctl arg is a pointer to a struct of type icp_analogdrv_tone_s. #define ICP_ANALOGDRV_TONE_OFF ioctl command for an FXS device to stop transmission of a tone on the line. The ioctl arg indicates the line on which to turn the tone generation off. #define ICP_ANALOG_DTMF_0 DTMF '0' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_1 DTMF '1' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_2 DTMF '2' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_3 DTMF '3' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_4 DTMF '4' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_5 DTMF '5' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. Reference Number: , Revision

16 1.6 Define Documentation #define ICP_ANALOG_DTMF_6 DTMF '6' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_7 DTMF '7' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_8 DTMF '8' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_9 DTMF '9' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_HASH DTMF '#' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_STAR DTMF '*' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_A DTMF 'A' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_B DTMF 'B' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_C DTMF 'C' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. Reference Number: , Revision

17 1.6 Define Documentation #define ICP_ANALOG_DTMF_D DTMF 'D' tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_DIAL DTMF dial tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_BUSY DTMF busy tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_RINGBACK DTMF ringback tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOG_DTMF_CALL_WAITING DTMF call waiting tone that can be generated on the line by an FXS device. This is passed to the client as part of a call to the ICP_ANALOGDRV_TONE_ON function using the icp_analogdrv_tone_s structure. #define ICP_ANALOGDRV_EVENT_ON_HOOK Event ID representing the on hook event/notification that can be generated by an FXS device. This is passed to the client as part of a call to the read() function using icp_analogdrv_event_s. #define ICP_ANALOGDRV_EVENT_OFF_HOOK Event ID representing the off hook event/notification that can be generated by an FXS device. It is passed to the client as part of a call to the read() function using icp_analogdrv_event_s. #define ICP_ANALOGDRV_EVENT_RING_ON Event ID representing the ring on event/notification that can be generated by an FXO device. It is passed to the client as part of a call to the read() function using icp_analogdrv_event_s. #define ICP_ANALOGDRV_EVENT_RING_OFF Event ID representing the ring off event/notification that can be generated by an FXO device. It is passed to the client as part of a call to the read() function using icp_analogdrv_event_s. #define ICP_ANALOGDRV_EVENT_POL_REV Event ID representing the polarity reversal notification that can be generated by an FXO device. Reference Number: , Revision

18 1.7 Typedef Documentation It is passed to the client as part of a call to the read() function using icp_analogdrv_event_s. 1.7 Typedef Documentation typedef struct icp_analogdrv_init_s icp_analogdrv_init_t Slot and predefined geo configuration. This structure contains the slot and the geo configuration. Parameter to the ICP_ANALOGDRV_INIT ioctl(). None typedef struct icp_analogdrv_event_s icp_analogdrv_event_t Event data structure. Contains the data for the event that is returned in the read() method. It indicates an event type and the line that generated the event. Format of the user buffer returned from a read() call. None typedef struct icp_analogdrv_pcm_config_s icp_analogdrv_pcm_config_t Pulse Code Modulation (PCM) configuration data for an FXO/FXS line. This structure contains the data needed to configure an FXO/FXS line. Set/get parameter for the ICP_ANALOGDRV_PCM_CONFIG_SET, ICP_ANALOGDRV_PCM_CONFIG_GET ioctl()s. None typedef struct icp_analogdrv_gen_reg_s icp_analogdrv_gen_reg_t Register write/read parameter structure. This structure contains the definition of the parameter for reading/writing value to a register. Read/Writing to an external FXO/FXS chip register is done using the ioctl commands ICP_ANALOGDRV_READ_REG and ICP_ANALOGDRV_WRITE_REG. Set/get parameter for the ICP_ANALOGDRV_WRITE_REG, ICP_ANALOGDRV_READ_REG ioctl()s. None Reference Number: , Revision

19 1.7 Typedef Documentation typedef struct icp_analogdrv_tone_s icp_analogdrv_tone_t Tone generation configuration for a line. This structure contains the configuration used to generate a tone on an FXS line using the ioctl command ICP_ANALOGDRV_TONE_ON. Set parameter for the ICP_ANALOGDRV_TONE_ON ioctl(). None Reference Number: , Revision

20 2 Framer device driver API 2.1 Detailed Description Public API for the Framer device driver. This API is designed for the Customer Reference Board E1/T1 Framer mezzanine card. The API is intended to be generic and may be used by customers as a reference for their platform specific framer drivers. This is a user space device control application with the ability to configure and receive events from the framer hardware. The EP80579 Customer Reference Board provides support for up to twelve E1/T1 external interfaces through the use of three Framer Mezzanine Modules, each containing one Framer device. This driver can control all three Framer Mezzanine Modules using the Device ID to differenciate between framer devices. The Device ID maps to a Framer Device (chip). This is used for all communication which relate to general operation of the Framer device, the client is required to specify the device. The deviceid is the same as the slot number which the card is plugged into. The allowable range for deviceid is from 0 to the number of hardware slots less 1. The line ID maps to a specific E1/T1/J1 port on a Framer device. The allowable range for lineid is from 0 to the number of supported lines on the device less 1. Typical predefined configurations are provided through the ICP_FRAMERDRV_CFG_* defines to configure the Framer device. These can be easily extended to create new configurations by the client. The Framer device Events that are available though the driver interface can be extended if required by the client. These are bit masks that can be OR'd together to specify which event should cause notifications. They are also used as a means of specifying what events have occurred. The Framer uses a Quad MVIP backplane clock. Tables are given below for the mapping of 4 E1 lines onto the 128 backplane Timeslots and for the mapping of 4 T1 lines onto the 128 backplane Timeslots. Mapping of E1 lines onto the Quad MVIP backplane Backplane Timeslot Number First E1 Line DS0 Number Second E1 Line DS0 Number Third E1 Line DS0 Number Fourth E1 Line DS0 Number Reference Number: , Revision

21 2.1 Detailed Description Mapping of T1 lines onto the Quad MVIP backplane Backplane Timeslot Number First T1 Line DS0 Number Second T1 Line DS0 Number Third T1 Line DS0 Number Fourth T1 Line DS0 Number 0-3 Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Unused Data Structures struct icp_framerdrv_stats_s This structure contains the statistics for a framer device line. struct icp_framerdrv_event_s Contains the data for an event that is returned in the icp_framerdrvread() method. 2.3 Defines #define ICP_FRAMERDRV_LOOPBACK_NONE No Loopback. #define ICP_FRAMERDRV_LOOPBACK_DIGITAL Digital Loopback. #define ICP_FRAMERDRV_LOOPBACK_LINE Line Loopback. #define ICP_FRAMERDRV_LOOPBACK_PAYLOAD Payload Loopback. #define ICP_FRAMERDRV_LINE_STATE_ACTIVE Active line state. #define ICP_FRAMERDRV_LINE_STATE_INACTIVE Inactive line state. #define ICP_FRAMERDRV_CFG_T1_CAS_B8ZS_ESF_SINGLE T1-CAS-B8ZS-ESF framer configuration. #define ICP_FRAMERDRV_CFG_T1_CAS_AMI_D4_SINGLE T1-CAS-AMI-D4/SF framer configuration. #define ICP_FRAMERDRV_CFG_T1_CCS_B8ZS_ESF_SINGLE Reference Number: , Revision

22 2.3 Defines T1-CCS-B8ZS-ESF framer configuration. #define ICP_FRAMERDRV_CFG_T1_CAS_B8ZS_ESF_QUAD T1-CCS-B8ZS-ESF framer configuration. #define ICP_FRAMERDRV_CFG_T1_CCS_B8ZS_ESF_QUAD T1-CCS-B8ZS-ESF framer configuration. #define ICP_FRAMERDRV_CFG_E1_CAS_HDB3_CRCMF_SINGLE E1-CAS-HDB3-CRC framer configuration. #define ICP_FRAMERDRV_CFG_E1_CCS_HDB3_CRCMF_SINGLE E1-CCS-HDB3-CRC framer configuration. #define ICP_FRAMERDRV_CFG_E1_CCS_AMI_BASIC_SINGLE E1-CCS-AMI-BASIC framer configuration. #define ICP_FRAMERDRV_CFG_E1_CAS_HDB3_CRCMF_QUAD E1-CAS-HDB3-CRC framer configuration. #define ICP_FRAMERDRV_CFG_E1_CCS_HDB3_CRCMF_QUAD E1 QUAD MVIP-CCS-HDB3-CRC framer configuration. #define ICP_FRAMERDRV_EVENT_LOS Event ID representing the LOS (Loss Of Signal) generated by the Framer device. #define ICP_FRAMERDRV_EVENT_LOFA Event ID representing the LOFA (Loss Of Framer Alignment) generated by the Framer device. #define ICP_FRAMERDRV_EVENT_AIS Event ID representing an AIS (Alarm Indicator Signal) failure generated by the Framer device. #define ICP_FRAMERDRV_EVENT_RED Event ID representing a Red Alarm. #define ICP_FRAMERDRV_EVENT_YEL Event ID representing a Yellow Alarm generated by the Framer device. #define ICP_FRAMERDRV_EVENT_OOF Event ID representing an OOF (Out Of Frame) defect generated by the Framer device. #define ICP_FRAMERDRV_EVENT_PDV Event ID representing a PDV (Pulse Density Violation) (16 consecutive zeros) defect generated by the Framer device. #define ICP_FRAMERDRV_EVENT_LOSMF Event ID representing a LOSMF (Loss Of Signaling Multi-Frame) defect generated by the Framer device. #define ICP_FRAMERDRV_EVENT_LOSCRCMF Event ID representing a LOSCRCMF (Loss Of CRC Multi-Frame) defect generated by the Framer device. #define ICP_FRAMERDRV_EVENT_TS16RAI Event ID representing a TS16RAI (Time Slot 16 Remote Alarm Indication) defect generated by the Framer device. #define ICP_FRAMERDRV_EVENT_COSS Event ID representing a COSS (Change of Signal State) generated by the Framer device. 2.4 Typedefs typedef icp_framerdrv_stats_s icp_framerdrv_stats_t This structure contains the statistics for a framer device line. typedef icp_framerdrv_event_s icp_framerdrv_event_t Contains the data for an event that is returned in the icp_framerdrvread() method. 2.5 Functions icp_status_t icp_framerdrvinit (unsigned int deviceid) Reference Number: , Revision

23 2.5 Functions Initializes the Framer device in a particular slot on the Customer Reference Board and allocates any memory needed. icp_status_t icp_framerdrvuninit (unsigned int deviceid) Uninitializes the Framer device in a particular slot on the Customer Reference Board and de-allocates any memory used. icp_status_t icp_framerdrvconfigset (unsigned int deviceid, unsigned int config) Configures the Framer device. icp_status_t icp_framerdrvconfigget (unsigned int deviceid, unsigned int *config) Gets the current framer configuration. icp_status_t icp_framerdrvloopbackset (unsigned int deviceid, unsigned int loopbackmode) Sets the loopback mode. icp_status_t icp_framerdrvreset (unsigned int deviceid) Resets the framer device. icp_status_t icp_framerdrvlinestateget (unsigned int deviceid, unsigned int lineid, unsigned int *linestate) Gets the line state. icp_status_t icp_framerdrvregwrite (unsigned int deviceid, uint32_t reg, uint8_t data) Writes to a register. icp_status_t icp_framerdrvregread (unsigned int deviceid, uint32_t reg, uint8_t *data) Reads from a register. icp_status_t icp_framerdrvnotificationsset (unsigned int deviceid, unsigned int lineid, uint32_t events) Configures Notifications. icp_status_t icp_framerdrvnotificationsget (unsigned int deviceid, unsigned int lineid, uint32_t *events) Gets notifications configuration. icp_status_t icp_framerdrvnumlinesperframerslotget (unsigned int deviceid, unsigned int *numlines) Gets number of lines on a framer. icp_status_t icp_framerdrvstatsget (unsigned int deviceid, unsigned int lineid, icp_framerdrv_stats_t *stats) Gets the stats for a framer card. icp_status_t icp_framerdrvread (unsigned int deviceid, icp_framerdrv_event_t *event, icp_boolean_t block) Reads an event from the driver. icp_status_t icp_framerdrvsignalstateset (unsigned int deviceid, unsigned int lineid, unsigned int timeslot, uint8_t state) Send signaling on a timeslot. icp_status_t icp_framerdrvsignalstateget (unsigned int deviceid, unsigned int lineid, unsigned int timeslot, uint8_t *state) Retrieve signaling on a timeslot. icp_status_t icp_framerdrvstatus (void) Prints the driver status. 2.6 Data Structure Documentation icp_framerdrv_stats_s Struct Reference Detailed Description This structure contains the statistics for a framer device line. This structure contains the statistics data for a framer device line that is returned by icp_framerdrvstatsget(). Each structure member contains the number of times that that error occurred. Reference Number: , Revision

24 2.6.1 icp_framerdrv_stats_s Struct Reference Format of the stats returned from a icp_framerdrvstatsget() call Data Fields unsigned int frm Framing errors. unsigned int oof OOF (Out of Frame) errors. unsigned int febe FEBE (Far End Block) errors. unsigned int t1bit T1 Bit errors. unsigned int e1crc E1 CRC errors. unsigned int cv Code Violations. unsigned int los LOS (Loss of Signal) events. unsigned int lofa LOFA (Loss of Frame Alignment) events. unsigned int ais AIS (Alarm Indication Signal) alarms. unsigned int e1rai_yellow_alrm E1 RAI (Remote Alarm Indication) (Yellow) alarms. unsigned int e1_lo_sig_mframe E1 Loss Of Signaling Multiframe. unsigned int e1_lo_crc_mframe E1 CRC Multiframe events. unsigned int e1_ts16rai E1 TS 16 RAI (Timeslot 16 Remote Alarm Indication) alarms Field Documentation unsigned int icp_framerdrv_stats_s::frm Framing errors. This is a count of the amount of Frame Alignment Signal Errors that have occurred. unsigned int icp_framerdrv_stats_s::oof OOF (Out of Frame) errors. This is a count of the amount of times the Out Of Frame condition occurred. unsigned int icp_framerdrv_stats_s::febe FEBE (Far End Block) errors. Raised if the first bit of the frames 14 and 16 is 0 (ITU-T G.706). unsigned int icp_framerdrv_stats_s::t1bit T1 Bit errors. Reference Number: , Revision

25 2.6.2 icp_framerdrv_event_s Struct Reference This event occurs whenever an incorrect or unexpected framing bit is received. unsigned int icp_framerdrv_stats_s::e1crc E1 CRC errors. Raised if one or more bits are erroneous, whenever CRC-Loss Of MultiFrame is off (ITU-T G.706). unsigned int icp_framerdrv_stats_s::cv Code Violations. Generated if there is a bipolar violations or excessive zeros. unsigned int icp_framerdrv_stats_s::los LOS (Loss of Signal) events. A LOS condition is declared when no pulses have been detected. unsigned int icp_framerdrv_stats_s::lofa LOFA (Loss of Frame Alignment) events. This error is reported if 3 consecutive Frame Alignment Signals have been received in error. unsigned int icp_framerdrv_stats_s::ais AIS (Alarm Indication Signal) alarms. Generated when an unframed all ones pattern is received. unsigned int icp_framerdrv_stats_s::e1rai_yellow_alrm E1 RAI (Remote Alarm Indication) (Yellow) alarms. A receive remote alarm indication (RAI) means the far end equipment has a problem with the signal it is receiving from the upstream equipment. unsigned int icp_framerdrv_stats_s::e1_lo_sig_mframe E1 Loss Of Signaling Multiframe. unsigned int icp_framerdrv_stats_s::e1_lo_crc_mframe E1 CRC Multiframe events. Activated if there is Loss Of Frame, and deactivated after one correct Frame Alignment Signal and two correct CRC-Multiframe frame Alignment Signals (ITU-T G.706). unsigned int icp_framerdrv_stats_s::e1_ts16rai E1 TS 16 RAI (Timeslot 16 Remote Alarm Indication) alarms. This error is triggered if an OOF condition has been present for 100 ms for E1 and 2.55s for T icp_framerdrv_event_s Struct Reference Reference Number: , Revision

26 2.6.2 icp_framerdrv_event_s Struct Reference Detailed Description Contains the data for an event that is returned in the icp_framerdrvread() method. Contains the data for an event that is returned in the icp_framerdrvread() method. It indicates an event type and the line that generated the event. Format of the user buffer returned from a icp_framerdrvread() call Data Fields unsigned int lineid E1/T1 line. uint32_t eventtype Event type as specified by the ICP_FRAMERDRV_EVENT_* defines. uint32_t ts Indicates which time slot a COSS occurred on by setting a 1 in that bit location Field Documentation unsigned int icp_framerdrv_event_s::lineid E1/T1 line. uint32_t icp_framerdrv_event_s::eventtype Event type as specified by the ICP_FRAMERDRV_EVENT_* defines. uint32_t icp_framerdrv_event_s::ts Indicates which time slot a COSS occurred on by setting a 1 in that bit location. 2.7 Define Documentation #define ICP_FRAMERDRV_LOOPBACK_NONE No Loopback. This define can be used as the loopbackmode parameter of the icp_framerdrvloopbackset function call. #define ICP_FRAMERDRV_LOOPBACK_DIGITAL Digital Loopback. This is a system (local) loopback. Traffic exercises the maximum amount of the Framer device before looping back to the system. This define can be used as the loopbackmode parameter of the icp_framerdrvloopbackset function call. #define ICP_FRAMERDRV_LOOPBACK_LINE Line Loopback. This is a network (remote) loopback. Traffic exercises the minimum amount of the Framer device before Reference Number: , Revision

27 2.7 Define Documentation looping back to the line. This define can be used as the loopbackmode parameter of the icp_framerdrvloopbackset function call. #define ICP_FRAMERDRV_LOOPBACK_PAYLOAD Payload Loopback. This is a network (remote) loopback. Traffic exercises the maximum amount of the Framer device before looping back to the line.this define can be used as the loopbackmode parameter of the icp_framerdrvloopbackset function call. #define ICP_FRAMERDRV_LINE_STATE_ACTIVE Active line state. The line is enabled and traffic is being received. This define can be used as the linestate parameter of the icp_framerdrvlinestateget function calls. #define ICP_FRAMERDRV_LINE_STATE_INACTIVE Inactive line state. The line is enabled but no traffic is being received. This define can be used as the linestate parameter of the icp_framerdrvlinestateget function calls. #define ICP_FRAMERDRV_CFG_T1_CAS_B8ZS_ESF_SINGLE T1-CAS-B8ZS-ESF framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: T1, CAS (Channel Associated Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_T1_CAS_AMI_D4_SINGLE T1-CAS-AMI-D4/SF framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: T1, CAS (Channel Associated Signaling) signaling, AMI (Alternate Mark Inversion) Encoding, D4/SF (Super Frame) Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_T1_CCS_B8ZS_ESF_SINGLE T1-CCS-B8ZS-ESF framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: T1, CCS (Common Channel Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_T1_CAS_B8ZS_ESF_QUAD T1-CCS-B8ZS-ESF framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates Reference Number: , Revision

28 2.7 Define Documentation that the Framer device is setup with following characteristics: T1 Backplane mode, CAS (Channel Associated Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_T1_CCS_B8ZS_ESF_QUAD T1-CCS-B8ZS-ESF framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: T1 Backplane mode, CCS (Common Channel Signaling) signaling, B8ZS (Bipolar with 8 Zero Substitution) Encoding, ESF (Extended Super Frame) Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_E1_CAS_HDB3_CRCMF_SINGLE E1-CAS-HDB3-CRC framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: E1, CAS (Channel Associated Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) Multi-Frame Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_E1_CCS_HDB3_CRCMF_SINGLE E1-CCS-HDB3-CRC framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: E1, CCS (Common Channel Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) Multi-Frame Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_E1_CCS_AMI_BASIC_SINGLE E1-CCS-AMI-BASIC framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: E1, CCS (Common Channel Signaling) signaling, AMI (Alternate Mark Inversion) Encoding, Basic Framing, Single Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_E1_CAS_HDB3_CRCMF_QUAD E1-CAS-HDB3-CRC framer configuration. This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: E1, CAS (Channel Associated Signaling) signaling, HDB3 (High Density Bipolar of order 3) Encoding, CRC (Cyclic Redundancy Check) Multi-Frame Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_CFG_E1_CCS_HDB3_CRCMF_QUAD E1 QUAD MVIP-CCS-HDB3-CRC framer configuration. Reference Number: , Revision

29 2.7 Define Documentation This define is provided as a default configuration for convenience and can be used as the config parameter of the icp_framerdrvconfigset and the * icp_framerdrvconfigget function calls. This define indicates that the Framer device is setup with following characteristics: E1, CCS (Common Channel Signaling) signaling, HDB3 (High Density Bipolar of order 3)Encoding, CRC (Cyclic Redundancy Check) Multi-Frame Framing, Quad Port Configuration, Quad MVIP (Multi-Vendor Integration Protocol) Backplane mode. #define ICP_FRAMERDRV_EVENT_LOS Event ID representing the LOS (Loss Of Signal) generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_LOFA Event ID representing the LOFA (Loss Of Framer Alignment) generated by the Framer device. This is passed to the client as part of a call to the read() function using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_AIS Event ID representing an AIS (Alarm Indicator Signal) failure generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_RED Event ID representing a Red Alarm. This is generated by the Framer device when an incorrect framing format is being received. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_YEL Event ID representing a Yellow Alarm generated by the Framer device. This is an RAI (Remote Alarm Indication). It indicates there is a red alarm condition on the remote device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_OOF Event ID representing an OOF (Out Of Frame) defect generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_PDV Event ID representing a PDV (Pulse Density Violation) (16 consecutive zeros) defect generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_LOSMF Event ID representing a LOSMF (Loss Of Signaling Multi-Frame) defect generated by the Framer device. Reference Number: , Revision

30 2.8 Typedef Documentation This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_LOSCRCMF Event ID representing a LOSCRCMF (Loss Of CRC Multi-Frame) defect generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_TS16RAI Event ID representing a TS16RAI (Time Slot 16 Remote Alarm Indication) defect generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. #define ICP_FRAMERDRV_EVENT_COSS Event ID representing a COSS (Change of Signal State) generated by the Framer device. This is passed to the client as part of a call to the icp_framerdrvread() function call using icp_framerdrv_event_s. 2.8 Typedef Documentation typedef struct icp_framerdrv_stats_s icp_framerdrv_stats_t This structure contains the statistics for a framer device line. This structure contains the statistics data for a framer device line that is returned by icp_framerdrvstatsget(). Each structure member contains the number of times that that error occurred. Format of the stats returned from a icp_framerdrvstatsget() call. typedef struct icp_framerdrv_event_s icp_framerdrv_event_t Contains the data for an event that is returned in the icp_framerdrvread() method. Contains the data for an event that is returned in the icp_framerdrvread() method. It indicates an event type and the line that generated the event. Format of the user buffer returned from a icp_framerdrvread() call. 2.9 Function Documentation icp_status_t icp_framerdrvinit ( unsigned int deviceid ) Reference Number: , Revision

31 2.9 Function Documentation Initializes the Framer device in a particular slot on the Customer Reference Board and allocates any memory needed. This function is responsible for initializing the framer device in a particular slot. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - The framer slot to be initialized. Blocking: Yes. Reentrant: No. Thread-safe: Yes. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The driver must have been successfully opened. Postcondition: Note: icp_status_t icp_framerdrvuninit ( unsigned int deviceid ) Uninitializes the Framer device in a particular slot on the Customer Reference Board and de-allocates any memory used. This function is responsible for uninitializing the framer device in a particular slot. Context: Calling function thread. Assumptions: Reference Number: , Revision

32 2.9 Function Documentation Side-Effects: Parameters: deviceid [IN] - The framer slot to be uninitialized. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: Postcondition: Note: If any framer devices have been initialized then this function must be called before the driver can be successfully removed from the system. icp_framerdrvinit(). icp_status_t icp_framerdrvconfigset ( unsigned int deviceid, unsigned int config ) Configures the Framer device. This function is responsible for configuring a framer device. This function needs to be recalled if the driver is ever reset using icp_framerdrvreset(). Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. config Reference Number: , Revision

33 2.9 Function Documentation Blocking: Yes. Reentrant: No. Thread-safe: No. [IN] - Predefined configuration number. This is one of the ICP_FRAMERDRV_CFG_* defines. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device in the selected slot must have been successfully initialized. Postcondition: Note: icp_framerdrvinit() icp_framerdrvreset(). icp_status_t icp_framerdrvconfigget ( unsigned int deviceid, unsigned int * config ) Gets the current framer configuration. This function is responsible for returning the current configuration of the framer device. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. *config [OUT] - This will be set to the current configuration of the selected device. This is one of the ICP_FRAMERDRV_CFG_* defines. Blocking: Yes. Reference Number: , Revision

34 2.9 Function Documentation Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully initialized and configured. Postcondition: Note: icp_framerdrvconfigset(). icp_status_t icp_framerdrvloopbackset ( unsigned int deviceid, unsigned int loopbackmode ) Sets the loopback mode. This function is responsible for setting the loopback mode for the framer device. Context: Calling function thread. Assumptions: Side-Effects: Parameters: Blocking: Yes. Reentrant: No. Thread-safe: No. deviceid loopbackmode [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. [IN] - Loopback mode. This is one of the ICP_FRAMERDRV_LOOPBACK_* defines. Reference Number: , Revision

35 2.9 Function Documentation Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully initialized. Postcondition: Note: icp_framerdrvinit(). icp_status_t icp_framerdrvreset ( unsigned int deviceid ) Resets the framer device. This function is responsible for resetting the framer. This should be used when there is to be a major configuration change,.i.e., changing the backplane from T1 to E1. icp_framerdrvconfigset() needs to be called after a reset, as all settings will be lost. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - The framer slot to be reset. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully initialized. Postcondition: Reference Number: , Revision

36 2.9 Function Documentation Note: icp_framerdrvconfigset(). icp_status_t icp_framerdrvlinestateget ( unsigned int deviceid, unsigned int lineid, unsigned int * linestate ) Gets the line state. This function is responsible for getting the current state of a line on the framer device. Context: Calling function thread. Assumptions: Side-Effects: Parameters: Blocking: Yes. Reentrant: No. Thread-safe: No. deviceid lineid *linestate [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. [IN] - E1/T1 line ID. [OUT] - E1/T1 line state. The returned line state is one of the ICP_FRAMERDRV_LINE_STATE_* defines. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully configured. Postcondition: Note: Reference Number: , Revision

37 2.9 Function Documentation icp_framerdrvconfigset(). icp_status_t icp_framerdrvregwrite ( unsigned int deviceid, uint32_t reg, uint8_t data ) Writes to a register. This function is responsible for writing a value to a specific register of the framer device. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. reg [IN] - The register that the data should be written to. Please refer to the relevant framer device data sheet for allowable register numbers. data [IN] - the data that is to be written. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully configured. Postcondition: Note: icp_framerdrvconfigset() icp_framerdrvregread(). Reference Number: , Revision

38 2.9 Function Documentation icp_status_t icp_framerdrvregread ( unsigned int deviceid, uint32_t reg, uint8_t * data ) Reads from a register. This function is responsible for reading a value to a specific register of the framer device. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. reg [IN] - The register that the data should be read from. Please refer to the relevant framer device data sheet for allowable register numbers. *data [IN] - the data that is returned from the register. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully configured. Postcondition: Note: icp_framerdrvconfigset() icp_framerdrvregwrite (). icp_status_t icp_framerdrvnotificationsset ( unsigned int deviceid, unsigned int lineid, uint32_t events Reference Number: , Revision

39 2.9 Function Documentation Configures Notifications. ) This function registers the events that the client requests notification for. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. lineid [IN] - E1/T1 line ID. events [IN] - indicates a 32-bit register which corresponds with the ICP_FRAMERDRV_EVENT_* defined events. Setting a bit will indicate that the client should be notified of this event. The register value passed down will overwrite all previous register values. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully initialized. Postcondition: Note: icp_framerdrvconfigset(). icp_status_t icp_framerdrvnotificationsget ( unsigned int deviceid, unsigned int lineid, uint32_t * events ) Reference Number: , Revision

40 2.9 Function Documentation Gets notifications configuration. This function returns the events that the client has requested notification for. Context: Calling function thread. Assumptions: Side-Effects: Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. lineid [IN] - E1/T1 line ID *events [IN] - indicates a 32-bit register which corresponds with the ICP_FRAMERDRV_EVENT_* defined events. If a bit is set then the client will be notified of this event. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully initialized. Postcondition: Note: icp_framerdrvconfigset(). icp_status_t icp_framerdrvnumlinesperframerslotget ( unsigned int deviceid, unsigned int * numlines ) Gets number of lines on a framer. This function is responsible for returning the number of lines (E1/T1) supported on the framer card. Context: Reference Number: , Revision

41 2.9 Function Documentation Assumptions: Side-Effects: Calling function thread. Parameters: deviceid *numlines [IN] - The framer slot to be configured. [OUT] - A positive return value indicates the number of supported lines on the Framer device. This is a constant value and is not affected by line state. Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The driver must have been successfully opened. Postcondition: Note: icp_framerdrvopen(). icp_status_t icp_framerdrvstatsget ( unsigned int deviceid, unsigned int lineid, icp_framerdrv_stats_t * stats ) Gets the stats for a framer card. This function is responsible for returning the stats on a framer card. Context: Calling function thread. Assumptions: Side-Effects: Reference Number: , Revision

42 2.9 Function Documentation Parameters: Blocking: Yes. Reentrant: No. Thread-safe: No. deviceid lineid *stats [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. [IN] - E1/T1 line ID. [OUT] - stats for the line. See the icp_framerdrv_stats_s structure for more details. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device must have been successfully initialized. Postcondition: Note: icp_framerdrvinit(). icp_status_t icp_framerdrvread ( unsigned int deviceid, icp_framerdrv_event_t * event, icp_boolean_t block ) Reads an event from the driver. This function is used by the client to get any single event from the driver that has been generated by the Framer device. Blocking and non blocking modes are supported. When called with blocking mode (blocking=true), calls to the function will block until an event has been delivered from the external device. When called with non blocking mode (blocking=false), the function immediately returns the next available event. If there are no events available, or if the framer device being read has not been configured the function returns ICP_STATUS_FAIL. Context: Calling function thread. Assumptions: Side-Effects: Reference Number: , Revision

43 2.9 Function Documentation Parameters: deviceid *event block [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. [OUT] - A structure of type icp_framerdrv_event_s. that specifies the event ID and the device and line on which it has occurred. [IN] - indicates whether the read is blocking or not. Blocking: This function can operate in both blocking and non blocking mode. The particular mode is chosen by setting the block parameter. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device that is being read from must have been successfully configured and event notifications should have been set. Postcondition: Note: icp_framerdrvconfig() icp_framerdrvnotificationsset(). icp_status_t icp_framerdrvsignalstateset ( unsigned int deviceid, unsigned int lineid, unsigned int timeslot, uint8_t state ) Send signaling on a timeslot. This function is used by the client to send signaling on A,B,C,D bits on a time slot for the selected line and framer device. Context: Calling function thread. Assumptions: Side-Effects: Reference Number: , Revision

44 2.9 Function Documentation Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. lineid [IN] - E1/T1 line ID. timeslot [IN] - the time slot on which the signal will be sent. state [IN] - the state to set. The location of the bits in state are as follows: 0x01 - D bit 0x02 - C bit 0x04 - B bit 0x08 - A bit Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device needs to have been successfully configured. Postcondition: Note: icp_framerdrvconfig() icp_status_t icp_framerdrvsignalstateget ( unsigned int deviceid, unsigned int lineid, unsigned int timeslot, uint8_t * state ) Retrieve signaling on a timeslot. This function is used by the client to get signaling bits A,B,C,D on a time slot for the selected line and framer device. Context: Calling function thread. Assumptions: Side-Effects: Reference Number: , Revision

45 2.9 Function Documentation Parameters: deviceid [IN] - Framer device. For the Customer Reference Board Framer Mezzanine card (one Framer device per card), this number is the same as the slot number in which the mezzanine card is plugged into. lineid [IN] - E1/T1 line ID. timeslot [IN] - the time slot on which to retrieve the signal data. *state [OUT] - the current state. The location of the bits in state are as follows: 0x01 - D bit 0x02 - C bit 0x04 - B bit 0x08 - A bit Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: The framer device needs to have been successfully configured. Postcondition: Note: icp_framerdrvconfig() icp_status_t icp_framerdrvstatus ( void ) Prints the driver status. This function is used by the client to print out the current state of each supported device. Context: Calling function thread. Assumptions: Side-Effects: Parameters: Reference Number: , Revision

46 2.9 Function Documentation Blocking: Yes. Reentrant: No. Thread-safe: No. Return values: ICP_STATUS_SUCCESS The function executed successfully. ICP_STATUS_FAIL* In the case where the function did not execute successfully the relevant ICP error code will be returned. Precondition: Postcondition: Note: Reference Number: , Revision

47 3 HSS data device driver API 3.1 Detailed Description This API defines an ioctl interface to the data device driver. This device driver can be called from user space using the standard ioctl interface. All calls take the format: ioctl(..., COMMAND, PARAM); This API defines the relevent COMMAND values and the corresponding structures or values to be used as PARAMs. A channel is configured on the device using ioctl calls. Up to 128 channels can be configured. The device file /dev/hss-datan will be used, where N is the channel number. This device driver is a serial (TTY) driver, using the synchronous PPP serial line discipline for HDLC channel provided by the Linux PPP subsystem. It acts as a bridge between the HSS access layer and the Linux PPP subsystem. The attachment of this line discipline to the serial HSS data driver is done by pppd. 3.2 Data Structures struct icp_hssdatadrv_channeladd_s Channel add parameter. 3.3 Defines #define ICP_HSSDATADRV_IOC_MAGIC Seed for ioctl commands. #define ICP_HSSDATADRV_PORT_UP ioctl command to bring up the port. #define ICP_HSSDATADRV_PORT_DOWN ioctl command to bring the port down. #define ICP_HSSDATADRV_CHAN_ADD ioctl command to add and configure a data channel. #define ICP_HSSDATADRV_CHAN_REMOVE ioctl command to remove (delete) the channel. #define ICP_HSSDATADRV_CHAN_UP ioctl command to enable data flow on the channel. #define ICP_HSSDATADRV_CHAN_DOWN ioctl command to disable data flow for the channel. #define ICP_HSSDATADRV_DEVICE_STATS ioctl command to display the stats for the device. #define ICP_HSSDATADRV_ALL_DEVICE_STATS ioctl command to display the stats for all devices. 3.4 Typedefs typedef icp_hssdatadrv_channeladd_s icp_hssdatadrv_channeladd_t Channel add parameter. 3.5 Enumerations Reference Number: , Revision

48 3.5 Enumerations enum icp_hssdatadrv_hdlc_sof_flag_type_t { ICP_HSSDATADRV_HDLC_SOF_SHARED_FLAG, ICP_HSSDATADRV_HDLC_SOF_ONE_FLAG, ICP_HSSDATADRV_HDLC_SOF_TWO_FLAGS, ICP_HSSDATADRV_HDLC_SOF_FLAG_TYPE_DELIMITER } HSS Start of Frame flag type. enum icp_hssdatadrv_hdlc_idle_pattern_t { ICP_HSSDATADRV_HDLC_IDLE_PATTERN_FLAG, ICP_HSSDATADRV_HDLC_IDLE_PATTERN_ONES, ICP_HSSDATADRV_HDLC_IDLE_PATTERN_DELIMITER } HSS HDLC Channel idle pattern. enum icp_hssdatadrv_hdlc_crc_size_t { ICP_HSSDATADRV_HDLC_CRC_SIZE_16, ICP_HSSDATADRV_HDLC_CRC_SIZE_32, ICP_HSSDATADRV_HDLC_CRC_SIZE_DELIMITER } HSS CRC size in bits. 3.6 Data Structure Documentation icp_hssdatadrv_channeladd_s Struct Reference Collaboration diagram for icp_hssdatadrv_channeladd_s: Reference Number: , Revision

49 3.6.1 icp_hssdatadrv_channeladd_s Struct Reference Detailed Description Channel add parameter. This structure contains the configuration for adding a data channel. Parameter to the ICP_HSSVOICEDRV_CHAN_ADD ioctl(). None Data Fields unsigned int portid HSS port ID 0 -> 2. icp_hssdrv_timeslot_map_t tsmap Timeslot map. icp_hssdatadrv_hdlc_crc_size_t hdlccrcsize Used to select the length in bits of the CRC appended to each frame on transmit. icp_hssdatadrv_hdlc_sof_flag_type_t hdlcsofflagtype Used to specify the number of flags to precede each frame. icp_hssdatadrv_hdlc_idle_pattern_t hdlcrxidlepattern Used to specify the HDLC RX idle pattern. icp_hssdatadrv_hdlc_idle_pattern_t hdlctxidlepattern Used to specify the HDLC Tx idle pattern. unsigned int channeldatainvert Used to select whether or not one's complement inversion is performed on the channel data before any other processing occurs. unsigned int channelbitendianness Used to configure the bit endianness of a channel. unsigned int channelbyteswap Used to configure whether bytes within each half-word (2 bytes) of data are swapped (1) or not (0) before transmitting out on the line and after receiving from the line. unsigned int robbedbitenable Used to configure whether the robbed bit is enabled (1) on this channel (56k channel) or disabled (0) on the channel (64k channel). unsigned int robbedbitvalue Used to configure the value of the robbed bit. unsigned int robbedbitlocation Used to configure the location of the Robbed Bit within each Byte of data Field Documentation unsigned int icp_hssdatadrv_channeladd_s::portid HSS port ID 0 -> 2. icp_hssdrv_timeslot_map_t icp_hssdatadrv_channeladd_s::tsmap Timeslot map. This field specifies the HSS timeslots the channels uses. icp_hssdatadrv_hdlc_crc_size_t icp_hssdatadrv_channeladd_s::hdlccrcsize Used to select the length in bits of the CRC appended to each frame on transmit. Reference Number: , Revision

50 3.7 Define Documentation Can be one of 16 bit or 32 bit. icp_hssdatadrv_hdlc_sof_flag_type_t icp_hssdatadrv_channeladd_s::hdlcsofflagtype Used to specify the number of flags to precede each frame. Can be one of flag sharing, one flag per frame, or two flags per frame. icp_hssdatadrv_hdlc_idle_pattern_t icp_hssdatadrv_channeladd_s::hdlcrxidlepattern Used to specify the HDLC RX idle pattern. The idle pattern can either be a repeated flag (0xFE) or all ones (0xFF). icp_hssdatadrv_hdlc_idle_pattern_t icp_hssdatadrv_channeladd_s::hdlctxidlepattern Used to specify the HDLC Tx idle pattern. The idle pattern can either be a repeated flag (0xFE) or all ones (0xFF). unsigned int icp_hssdatadrv_channeladd_s::channeldatainvert Used to select whether or not one's complement inversion is performed on the channel data before any other processing occurs. Set this argument to (1) in order enable one's complement inversion of the bits. Set this argument to (0) to disable the bit order inversion. unsigned int icp_hssdatadrv_channeladd_s::channelbitendianness Used to configure the bit endianness of a channel. Set this argument to (1) for MSb first, or (0) for LSb first. unsigned int icp_hssdatadrv_channeladd_s::channelbyteswap Used to configure whether bytes within each half-word (2 bytes) of data are swapped (1) or not (0) before transmitting out on the line and after receiving from the line. unsigned int icp_hssdatadrv_channeladd_s::robbedbitenable Used to configure whether the robbed bit is enabled (1) on this channel (56k channel) or disabled (0) on the channel (64k channel). unsigned int icp_hssdatadrv_channeladd_s::robbedbitvalue Used to configure the value of the robbed bit. Correct values are 0 or 1. This parameter will only be used if the robbed bit is enabled. unsigned int icp_hssdatadrv_channeladd_s::robbedbitlocation Used to configure the location of the Robbed Bit within each Byte of data. Available locations are: 0, the Robbed Bit is in position 0 of each byte (LSb); 7, the Robbed Bit is in position 7 of each byte (MSb). 3.7 Define Documentation #define ICP_HSSDATADRV_IOC_MAGIC Reference Number: , Revision

51 3.8 Typedef Documentation Seed for ioctl commands. #define ICP_HSSDATADRV_PORT_UP ioctl command to bring up the port. The parameter is a pointer to a data structure of type icp_hssdrv_portup_s containing port number, the predefined mezzanine card configuration and loopback mode. #define ICP_HSSDATADRV_PORT_DOWN ioctl command to bring the port down. The port may then be brought up again with a new configuration. The parameter is an integer indicating the port number to bring down. (0-3). #define ICP_HSSDATADRV_CHAN_ADD ioctl command to add and configure a data channel. The parameter is a pointer to data structure of type icp_hssdatadrv_channeladd_s. Data flow must be enabled by a subsequent call to the ICP_HSSDATADRV_CHAN_UP IOCTL. #define ICP_HSSDATADRV_CHAN_REMOVE ioctl command to remove (delete) the channel. The client shall put the channel down before calling this. #define ICP_HSSDATADRV_CHAN_UP ioctl command to enable data flow on the channel. #define ICP_HSSDATADRV_CHAN_DOWN ioctl command to disable data flow for the channel. #define ICP_HSSDATADRV_DEVICE_STATS ioctl command to display the stats for the device. The parameter is an integer argument which can be used to reset the stats for the device. A 0 indicates that stats should not be reset, while a 1 indicates that stats should be reset. #define ICP_HSSDATADRV_ALL_DEVICE_STATS ioctl command to display the stats for all devices. Stats are not reset. 3.8 Typedef Documentation typedef struct icp_hssdatadrv_channeladd_s icp_hssdatadrv_channeladd_t Channel add parameter. This structure contains the configuration for adding a data channel. Parameter to the ICP_HSSVOICEDRV_CHAN_ADD ioctl(). Reference Number: , Revision

52 3.9 Enumeration Type Documentation None 3.9 Enumeration Type Documentation enum icp_hssdatadrv_hdlc_sof_flag_type_t HSS Start of Frame flag type. HSS start of frame flag types. Used to decide if flag sharing is to be used. Choices are that the SOF flag is the same as the previous frames' End Of Frame flag, there is one SOF flag at the start of the frame, or there are two SOF flags at the start of the frame. Enumerator: ICP_HSSDATADRV_HDLC_SOF_SHARED_FLAG EOF and SOF shared when two packets back to back. ICP_HSSDATADRV_HDLC_SOF_ONE_FLAG One SOF Flag. ICP_HSSDATADRV_HDLC_SOF_TWO_FLAGS Two SOF Flags. ICP_HSSDATADRV_HDLC_SOF_FLAG_TYPE_DELIMITER Enum delimiter for error check. enum icp_hssdatadrv_hdlc_idle_pattern_t HSS HDLC Channel idle pattern. Used to set the HDLC channel idle transmit and receive pattern. Enumerator: ICP_HSSDATADRV_HDLC_IDLE_PATTERN_FLAG Idle is repeated '0xFE' flag. ICP_HSSDATADRV_HDLC_IDLE_PATTERN_ONES Idle is all ones. ICP_HSSDATADRV_HDLC_IDLE_PATTERN_DELIMITER Enum delimiter for error checks. enum icp_hssdatadrv_hdlc_crc_size_t HSS CRC size in bits. Used to set the HSS HDLC Channel's CRC size. Enumerator: ICP_HSSDATADRV_HDLC_CRC_SIZE_16 ICP_HSSDATADRV_HDLC_CRC_SIZE_32 ICP_HSSDATADRV_HDLC_CRC_SIZE_DELIMITER 16 bit CRC is being used. 32 bit CRC is being used. Enum delimiter for error checks. Reference Number: , Revision

53 4 Definitions common to the HSS voice and HSS data drivers. 4.1 Detailed Description Common defines and structures used by voice and data drivers including the HSS port configuration and the channel timeslot configuration. 4.2 Data Structures struct icp_hssdrv_portup_s Port up configuration. struct icp_hssdrv_timeslot_map_s Timeslot map for a channel onto a HSS port. 4.3 Defines #define ICP_HSSDRV_PORT_E1_FRAMER_MEZZANINE_CONFIG Configuration for the reference platform E1 framer mezzanine. #define ICP_HSSDRV_PORT_T1_FRAMER_MEZZANINE_CONFIG Configuration for the reference platform T1 framer mezzanine. #define ICP_HSSDRV_PORT_HMVIP_FRAMER_MEZZANINE_CONFIG Configuration for the reference platform in H-MVIP mode. #define ICP_HSSDRV_PORT_ANALOG_VOICE_MEZZANINE_CONFIG Configuration for the reference platform analog voice mezzanine. 4.4 Typedefs typedef icp_hssdrv_portup_s icp_hssdrv_portup_t Port up configuration. typedef icp_hssdrv_timeslot_map_s icp_hssdrv_timeslot_map_t Timeslot map for a channel onto a HSS port. 4.5 Enumerations enum icp_hssdrv_loopback_t { ICP_HSSDRV_EXTERNAL_LOOPBACK, ICP_HSSDRV_INTERNAL_LOOPBACK, ICP_HSSDRV_NO_LOOPBACK, ICP_HSSDRV_EXTERNAL_LOOPBACK_DELIMITER } HSS Loopback Setting. 4.6 Data Structure Documentation Reference Number: , Revision

54 4.6.1 icp_hssdrv_portup_s Struct Reference icp_hssdrv_portup_s Struct Reference Detailed Description Port up configuration. This structure contains the data required to configure and enable a HSS port. Parameter to the voice and data driver PORT_UP IOCTLs. None Data Fields unsigned int portid HSS port ID 0 -> 2. unsigned int port_config Selects a predefined port configuration for a particular mezzanine card, one of ICP_HSSDRV_PORT_E1_FRAMER_MEZZANINE_CONFIG, ICP_HSSDRV_PORT_T1_FRAMER_MEZZANINE_CONFIG, ICP_HSSDRV_PORT_HMVIP_FRAMER_MEZZANINE_CONFIG, ICP_HSSDRV_PORT_ANALOG_VOICE_MEZZANINE_CONFIG. icp_hssdrv_loopback_t loopbackmode Loopback mode for this port Field Documentation unsigned int icp_hssdrv_portup_s::portid HSS port ID 0 -> 2. unsigned int icp_hssdrv_portup_s::port_config Selects a predefined port configuration for a particular mezzanine card, one of ICP_HSSDRV_PORT_E1_FRAMER_MEZZANINE_CONFIG, ICP_HSSDRV_PORT_T1_FRAMER_MEZZANINE_CONFIG, ICP_HSSDRV_PORT_HMVIP_FRAMER_MEZZANINE_CONFIG, ICP_HSSDRV_PORT_ANALOG_VOICE_MEZZANINE_CONFIG. These configurations are hard coded in the driver and can be modified for a customer specific mezzanine card. icp_hssdrv_loopback_t icp_hssdrv_portup_s::loopbackmode Loopback mode for this port icp_hssdrv_timeslot_map_s Struct Reference Detailed Description Timeslot map for a channel onto a HSS port. Reference Number: , Revision

55 4.6.2 icp_hssdrv_timeslot_map_s Struct Reference This structure contains the timeslot map information for each port. Setting a bit high (1) indicates that timeslot is required. The timeslot bit map for E1/T1 lines 1, 2 and 3 are only relevant if the HSS Frame contains > 32 timeslots, i.e. MVIP is enabled and we have 4 E1 lines on a single port. This series of bit masks represents the timeslots [0 -> 31] for each HSS line. LSb represents timeslot #0, MSb represents timeslot #31 for a line. Sample configurations: 0x , 0x , 0x , 0x corresponds to timeslots 1 on line 2. 0x , 0x , 0x , 0x corresponds to timeslots 8,9 on line 2 and timeslots 24,25 on line 2. This example is a wideband voice channel configuration for the Si3220 SLIC/CODEC (16 16khz, i.e. 2 sets of 2 timeslots separated by 16 timeslots). 0x , 0x , 0x , 0x corresponds to timeslots 4 and 5 on line 1. This example could be a 16 bit linear narrowband voice channel. 0x , 0xFFFFFFFE, 0x , 0x corresponds to timeslots 1 to 31 on line 1. Channel timeslot configuration. None Data Fields u32 line0_timeslot_bit_map Timeslot bit map for line 0. u32 line1_timeslot_bit_map Timeslot bit map for line 1. u32 line2_timeslot_bit_map Timeslot bit map for line 2. u32 line3_timeslot_bit_map Timeslot bit map for line Field Documentation u32 icp_hssdrv_timeslot_map_s::line0_timeslot_bit_map Timeslot bit map for line 0. u32 icp_hssdrv_timeslot_map_s::line1_timeslot_bit_map Timeslot bit map for line 1. u32 icp_hssdrv_timeslot_map_s::line2_timeslot_bit_map Timeslot bit map for line 2. u32 icp_hssdrv_timeslot_map_s::line3_timeslot_bit_map Timeslot bit map for line 3. Reference Number: , Revision

56 4.7 Define Documentation 4.7 Define Documentation #define ICP_HSSDRV_PORT_E1_FRAMER_MEZZANINE_CONFIG Configuration for the reference platform E1 framer mezzanine. #define ICP_HSSDRV_PORT_T1_FRAMER_MEZZANINE_CONFIG Configuration for the reference platform T1 framer mezzanine. #define ICP_HSSDRV_PORT_HMVIP_FRAMER_MEZZANINE_CONFIG Configuration for the reference platform in H-MVIP mode. #define ICP_HSSDRV_PORT_ANALOG_VOICE_MEZZANINE_CONFIG Configuration for the reference platform analog voice mezzanine. 4.8 Typedef Documentation typedef struct icp_hssdrv_portup_s icp_hssdrv_portup_t Port up configuration. This structure contains the data required to configure and enable a HSS port. Parameter to the voice and data driver PORT_UP IOCTLs. None typedef struct icp_hssdrv_timeslot_map_s icp_hssdrv_timeslot_map_t Timeslot map for a channel onto a HSS port. This structure contains the timeslot map information for each port. Setting a bit high (1) indicates that timeslot is required. The timeslot bit map for E1/T1 lines 1, 2 and 3 are only relevant if the HSS Frame contains > 32 timeslots, i.e. MVIP is enabled and we have 4 E1 lines on a single port. This series of bit masks represents the timeslots [0 -> 31] for each HSS line. LSb represents timeslot #0, MSb represents timeslot #31 for a line. Sample configurations: 0x , 0x , 0x , 0x corresponds to timeslots 1 on line 2. 0x , 0x , 0x , 0x corresponds to timeslots 8,9 on line 2 and timeslots 24,25 on line 2. This example is a wideband voice channel configuration for the Si3220 SLIC/CODEC (16 16khz, i.e. 2 sets of 2 timeslots separated by 16 timeslots). 0x , 0x , 0x , 0x corresponds to timeslots 4 and 5 on line 1. This example could be a 16 bit linear narrowband voice channel. 0x , 0xFFFFFFFE, 0x , 0x corresponds to timeslots 1 to 31 on line 1. Reference Number: , Revision

57 4.8 Typedef Documentation None Channel timeslot configuration. 4.9 Enumeration Type Documentation enum icp_hssdrv_loopback_t HSS Loopback Setting. Used to enable/disable internal/external loop back. When the internal or external loopback settings are selected the pre-defined configuration e.g. ICP_HSSDRV_PORT_HMVIP_FRAMER_MEZZANINE_CONFIG is ignored and an E1 port speed is set. Please note that for internal loopback a mezzanine card must not be connected to the HSS port. Enumerator: ICP_HSSDRV_EXTERNAL_LOOPBACK ICP_HSSDRV_INTERNAL_LOOPBACK ICP_HSSDRV_NO_LOOPBACK ICP_HSSDRV_EXTERNAL_LOOPBACK_DELIMITER Enable the external loop back, all received data looped to transmit. Enable the internal loop back, all transmitted data looped to receive. This Setting is incompatible with any peripheral connected to the port configured in this mode. No loopback enabled on the port. Enum delimiter for error checks. Reference Number: , Revision

58 5 HSS voice device driver API 5.1 Detailed Description This device driver can be called from user space. A character device can be opened using the system call open(). The file name is "/dev/hss-voice". This device can be poll(), read(), write(), and release() like a standard character device. This device driver can be called from user space using the standard ioctl interface. A channel is configured on the device using ioctl calls. Up to 128 channels can be configured. One limitation is that no more than 64 channels can be associated to any one file descriptor. Since standard POSIX file poll/read/write operations do not allow the inclusion of extra (custom) parameters (such as the channel ID), the Voice channel ID is embedded in the user buffer passed in read/write calls. When reading/writing voice data to/from the device with calls to read() and write(), the format of the user buffer is as follows: len channelid payload len channelid payload etc. len (16 bit) is the length in bytes of the voice packet payload. The voice packet payload is a multiple of 4 bytes. 16 bits are used for future proofing. Additionally, when combined with the 16 bit channelid, the payload is always 32 bit aligned. As the user buffer is a char array the order of the len bytes needs to be specified. It is passed in the order MSB LSB. channelid (16 bit) is the channel ID of the voice packet payload. Passing len and channelid in the user buffer for each packet can simplify the client code - it doesn't have to remember fixed offsets for each packet in a buffer. As the user buffer is a char array the order of the channelid bytes needs to be specified. It is passed in the order MSB LSB. payload (len bytes) is the voice packet payload for the channelid. With the above user buffer format, write() gives the client the options to 1) submit a single packet for a single channel 2) submit multiple packets for a single channel or 3) submit multiple packets for multiple channels. read() on a file descriptor returns multiple packets together in the user buffer, with up to one packet for each registered channel for the file descriptor. The client can choose to open() multiple file descriptors and register a single channel per descriptor, thus receiving a single packet per read() on a descriptor. Alternatively the client can register multiple channels for multiple descriptors, thus receiveing multiple packets per read() on a particular descriptor. File descriptors can be opened in blocking or non-blocking mode. At any given time, all open file descriptors must be of the same mode. Attempts to open file descriptors in different modes at the same time will result in a fail. For example, a first file descriptor could be opened in blocking mode. All subsequent opens should be in blocking mode. All current open file descriptors in blocking mode should be closed for an open to succeed in non-blocking mode. By default the driver operates in blocking mode. Calls to read() blocks until received packets are available for all registered channels. Calls to write() do not block. When configured for non blocking mode (O_NONBLOCK), calls to read() immediately return available received packets (one packet per registered channel). If there are no packets available it returns 0. Reference Number: , Revision

59 5.1 Detailed Description Calls to write() buffer as many full packets as there is space internally for transmission. The returned length indicates the number of bytes written (including the length and channelid fields). The voicepacketsize and number of timeslots in the tsmap configured at channel setup defines the read() block rate for a channel. e.g. 1 timeslot for a voicepacketsize of 80 bytes for an 2.048MHz corresponds to a packet read() every 10msec. If the client configures multiple channels for the same file descriptor, calls to read() for that file descriptor will block until data is available for the slowest channel. The client must not process channels with different codec intervals on the same file descriptor. In blocking mode, the poll() method may be used to determine whether the read()function will block when called. The poll() method should not be used in non-blocking mode. HSS Voice Driver allows clients to utilize multiple threading. There are some restrictions that apply: poll() methods can only be called simultaneously if they are on different file descriptors. read() methods can only be called simultaneously if they are on different file descriptors. poll() and read() methods can only be called simultaneously if they are on different file descriptors. write() methods can be called simultaneously. ioctl() methods can not be called simultaneously. It is recommended that the client synchronizes data path methods such as poll()/read()/write() with control ioctl() commands on a file descriptor. However, the client can use both simultaneously as long as it can handle the race conditions (examples below) that may be introduced by dynamically changing the state of channels simultaneous with performing data path operations on those same channels. Example 1: poll() is called on a file descriptor that has 2 channels associated with it. It returns that data is ready on both channels and therefore a call to read() will not block. ioctl() commands are used to add another channel on which receive data is not ready. read() is called and is expected to not block as poll() has indicated this. As there is no data ready on the newly added channel, read() blocks. Example 2: A blocking read() is called on a file descriptor that has 2 channels associated with it. At this point an ioctl() command to delete 1 channel is run. Depending on the stage of the read() when the ioctl command is run, the read() may return data for both channels, or just the channel that is enabled. Please note that for blocking read(), any channel that is causing the read() to block will have its state checked every 10mS to ensure that it is still enabled and therefore data is expected on it. The poll() method should be given a timeout by the client in order that it does not block indefinitely if there is a state change. The release() method should only be called after any other calls are completed. It should not be attempted simultaneously with other methods. None of the methods provided by the HSS Voice Driver are callable as part of an Interrupt Service Routine. 5.2 Data Structures struct icp_hssvoicedrv_channeladd_s Channel add parameter. struct icp_hssvoicedrv_channelbypass_s Channel Bypass parameter. 5.3 Defines #define ICP_HSSVOICEDRV_IOC_MAGIC Seed for ioctl commands. #define ICP_HSSVOICEDRV_PORT_UP ioctl command to bring up the port. #define ICP_HSSVOICEDRV_PORT_DOWN Reference Number: , Revision

60 5.3 Defines ioctl command to bring down the port. #define ICP_HSSVOICEDRV_CHAN_ADD ioctl command to add and configure a voice channel. #define ICP_HSSVOICEDRV_CHAN_REMOVE ioctl command to remove (delete) the channel, specified by the channelid in the parameter. #define ICP_HSSVOICEDRV_CHAN_UP ioctl command to enable data flow on the channelid, specified by the channelid on the parameter. #define ICP_HSSVOICEDRV_CHAN_DOWN ioctl command to disable data flow for the channel id specified in the parameter. #define ICP_HSSVOICEDRV_CHAN_BYPASS_ENABLE ioctl command to create a unidirectional channel bypass between the channels specified in the data structure of type icp_hssvoicedrv_channelbypass_s passed as parameter. #define ICP_HSSVOICEDRV_CHAN_BYPASS_DISABLE ioctl command to remove a unidirectional channel bypass between the channels specified in the data structure of type icp_hssvoicedrv_channelbypass_s passed as parameter. #define ICP_HSSVOICEDRV_STATS ioctl command to display the stats for the HSS Voice Driver. 5.4 Typedefs typedef icp_hssvoicedrv_channeladd_s icp_hssvoicedrv_channeladd_t Channel add parameter. typedef icp_hssvoicedrv_channelbypass_s icp_hssvoicedrv_channelbypass_t Channel Bypass parameter. 5.5 Data Structure Documentation icp_hssvoicedrv_channeladd_s Struct Reference Collaboration diagram for icp_hssvoicedrv_channeladd_s: Reference Number: , Revision

61 5.5.1 icp_hssvoicedrv_channeladd_s Struct Reference Detailed Description Channel add parameter. This structure contains the configuration for adding a voice channel. Parameter to the ICP_HSSVOICEDRV_CHAN_ADD ioctl(). None Data Fields unsigned int channelid Client provided channel ID from 0 -> 127. unsigned int portid HSS port ID 0 -> 3. unsigned int voicepacketsize Set this argument to configure the size of the voice packets in bytes for this channel. icp_hssdrv_timeslot_map_t tsmap Timeslot Map. unsigned int voiceidleaction This argument is used to configure the Tx idle action to (0) transmit the pattern set in the voiceidlepattern argument or (1) to repeat the last frame. unsigned int voiceidlepattern If the voiceidleaction argument is set to (0) this argument is used to configure the Tx idle pattern as a value from 0 to 0xFF. unsigned int channeldatainvert Reference Number: , Revision