From patchwork Tue Mar 5 12:41:34 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandeep Singh X-Patchwork-Id: 224995 X-Patchwork-Delegate: galak@kernel.crashing.org Return-Path: X-Original-To: patchwork-incoming@ozlabs.org Delivered-To: patchwork-incoming@ozlabs.org Received: from ozlabs.org (localhost [IPv6:::1]) by ozlabs.org (Postfix) with ESMTP id 1247F2C035C for ; Tue, 5 Mar 2013 23:42:40 +1100 (EST) Received: from co9outboundpool.messaging.microsoft.com (co9ehsobe004.messaging.microsoft.com [207.46.163.27]) (using TLSv1 with cipher AES128-SHA (128/128 bits)) (Client CN "mail.global.frontbridge.com", Issuer "Microsoft Secure Server Authority" (not verified)) by ozlabs.org (Postfix) with ESMTPS id F09E02C0333 for ; Tue, 5 Mar 2013 23:42:08 +1100 (EST) Received: from mail119-co9-R.bigfish.com (10.236.132.250) by CO9EHSOBE015.bigfish.com (10.236.130.78) with Microsoft SMTP Server id 14.1.225.23; Tue, 5 Mar 2013 12:42:00 +0000 Received: from mail119-co9 (localhost [127.0.0.1]) by mail119-co9-R.bigfish.com (Postfix) with ESMTP id AD7E26C015A; Tue, 5 Mar 2013 12:42:00 +0000 (UTC) X-Forefront-Antispam-Report: CIP:70.37.183.190; KIP:(null); UIP:(null); IPV:NLI; H:mail.freescale.net; RD:none; EFVD:NLI X-SpamScore: -1 X-BigFish: VS-1(zzzz1f42h1ee6h1de0h1202h1e76h1d1ah1d2ahzz8275bh15d4Iz2dh2a8h668h839he5bhf0ah1288h12a5h12a9h12bdh12e5h137ah139eh13b6h1441h1504h1537h162dh1631h1758h1898h18e1h1946h19b5h1ad9h1b0ah1155h) Received: from mail119-co9 (localhost.localdomain [127.0.0.1]) by mail119-co9 (MessageSwitch) id 1362487317418578_8925; Tue, 5 Mar 2013 12:41:57 +0000 (UTC) Received: from CO9EHSMHS026.bigfish.com (unknown [10.236.132.238]) by mail119-co9.bigfish.com (Postfix) with ESMTP id 6161544005C; Tue, 5 Mar 2013 12:41:57 +0000 (UTC) Received: from mail.freescale.net (70.37.183.190) by CO9EHSMHS026.bigfish.com (10.236.130.36) with Microsoft SMTP Server (TLS) id 14.1.225.23; Tue, 5 Mar 2013 12:41:57 +0000 Received: from tx30smr01.am.freescale.net (10.81.153.31) by 039-SN1MMR1-003.039d.mgd.msft.net (10.84.1.16) with Microsoft SMTP Server (TLS) id 14.2.328.11; Tue, 5 Mar 2013 12:41:56 +0000 Received: from nmglablinux22.zin33.ap.freescale.net (nmglablinux22.zin33.ap.freescale.net [10.232.20.244]) by tx30smr01.am.freescale.net (8.14.3/8.14.0) with ESMTP id r25CfqHg020636; Tue, 5 Mar 2013 05:41:53 -0700 From: Sandeep Singh To: Subject: [PATCH 1/4][v2] Adding Documentation for TDM Date: Tue, 5 Mar 2013 18:11:34 +0530 Message-ID: <1362487297-19702-1-git-send-email-Sandeep@freescale.com> X-Mailer: git-send-email 1.7.6.GIT MIME-Version: 1.0 X-OriginatorOrg: freescale.com Cc: Sandeep Singh , Poonam Aggrwal , linux-arm-kernel@lists.infradead.org X-BeenThere: linuxppc-dev@lists.ozlabs.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Linux on PowerPC Developers Mail List List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: linuxppc-dev-bounces+patchwork-incoming=ozlabs.org@lists.ozlabs.org Sender: "Linuxppc-dev" tdm-summary.txt contains general description about TDM. tdm-framework.txt contains specific description of TDM framework. Signed-off-by: Sandeep Singh Signed-off-by: Poonam Aggrwal --- Documentation/tdm/tdm-framework.txt | 264 +++++++++++++++++++++++++++++++++++ Documentation/tdm/tdm-summary.txt | 103 ++++++++++++++ 2 files changed, 367 insertions(+), 0 deletions(-) create mode 100644 Documentation/tdm/tdm-framework.txt create mode 100644 Documentation/tdm/tdm-summary.txt diff --git a/Documentation/tdm/tdm-framework.txt b/Documentation/tdm/tdm-framework.txt new file mode 100644 index 0000000..e8704a4 --- /dev/null +++ b/Documentation/tdm/tdm-framework.txt @@ -0,0 +1,264 @@ +This document gives an overview of TDM framework and its interface with low +level drivers and upper level users/clients. + +Terminology: +============ +1. Adapter or TDM adapter: Refers to an instance of TDM controller/device on + the system. +2. TDM channel: The channel is the smallest entity on which all the TDM + read/write operations will occur. Technically all channels map to a set of + consecutive time slots on the physical TDM frame. The channels will be + dynamically created and destroyed using tdm_open_channel and + tdm_close_channel. +3. TDM frame: Is a set of TDM channels which is transmitted sequentially over + time. The frame start is identified by a frame sync signal that is briefly + asserted at the beginning of each frame. + +<----------TDM Frame 0------------>|<-----TDM Frame 1-----------------> + +|----|----|----|----|----|----|----|----|----|----|----|----|----|----| +| 0 | 1 | 2 | 3 | 4 | ...| n | 0 | 1 | 2 | 3 | 4 | ...| n | +|----|----|----|----|----|----|----|----|----|----|----|----|----|----| +<----> <----> + ch 0 ch 0 + +4. TDM client: Application/driver which registers with TDM framework to use TDM + device. + +TDM modes: +========== +A TDM device can operate in one of the following modes: +1. Single port full mode - Single user, no interleaving +2. Single port channelised mode (raw, E1, T1)- many users using different channels +3. Single port fractional mode - +4. Multi port mode - multiple users using different ports in different configurations. + +All the above configurations differ in number of TDM client they support, +number of TDM channels and number of TDM ports. + +Currently we are supporting only single port channelised mode. Hence all the explanations below +refer to channelised mode of TDM. This framework can be easily extended to support other modes. + +Single port Channelised Mode: +============================= +In single port channelised mode there can be only one port and each channel can have only one time slot. +The number of active channels can be less than the maximum supported channels/slots. + +<----------TDM Frame 0------------>|<-----TDM Frame 1-----------------> + +|----|----|----|----|----|----|----|----|----|----|----|----|----|----| +| 0 | 1 | 2 | 3 | 4 | ...| n | 0 | 1 | 2 | 3 | 4 | ...| n |... +|----|----|----|----|----|----|----|----|----|----|----|----|----|----| +<----><---> <----> + ch 0 ch1 ch 0 +client0 client1 + +TDM Subsystem Overview: +======================= + +------------------------------------------------------------------- + |------------------------| + | kernel mode TDM clients| + |------------------------| + || + || + client register + || + || + \/ + ______________________________________________________________ + | | + | client interface | + |------------------------------------------------------------| + | TDM Subsystem Framework | + | (tdm-core.c) | + | | + | ->buffer handling | + | ->interleaving/de-interleaving | + | | + |------------------------------------------------------------| + | TDM interface Line control interface | + |____________________________________________________________| + /\ /\ + || || + device register device register + || || + || || + + fsl_tdm.c ucc_tdm.c slic_zarlink.c framer.c +-------------------------------------------------------------------------- +_______________________ _____________________ ________ ________ +| | | | | | | | +|[h/w] TDM controller | |UCC TDM controller | | SLIC | |Framer| +|_____________________| |___________________| |______| |______| + + +TDM Adapter Registration: +========================= +All the TDM adapter drivers will get registered as platform drivers to Linux. +For every instance of the TDM adapter the relevant driver will be probed. +As part of probe the driver will +1. Do the basic initialization in terms of memory allocation for various + driver specific data structures, interrupts registration, etc. +2. Initialize the TDM adapter and configure it in default configuration. + like operating mode, number of channels, channel type, etc. +3. Add the TDM adapter to the TDM Framework via tdm_add_adapter() API. + As a result TDM framework will add this adapter to it's queue of + available adapters. As part of this adapter registration TDM framework + is also supplied a list of access algorithms for the particular TDM + adapter. +4. Notifies the clients + +TDM Client Registration: +======================== +Every TDM client gets itself registered with the TDM framework layer as +a TDM driver using the API tdm_add_driver(). As part of this the TDM client +supplies to the TDM framework the adapter with which it wants to hook and +the function pointers of attach and detach functions which must be called +as soon as the requested adapter is available. + +As a result the TDM framework keeps association of TDM adapters and TDM +client drivers. +As soon as this association gets established a tasklet is created for the +adapter which is handled by tdm_data_tasklet_fn. The primary function of +this tasklet acts as an interface to transfer the TDM data between the +TDM adapter and the TDM client drivers. + +Currently TDM adaper can only be used in the default configuration. +ie the configuration cannot be modified by TDM clients. This will be +enhanced in future. + +Line Control Device Registration: +================================= +Each line control device has to add itself to list of available tdm phy device +list by calling tdm_add_phy. At this point the framework traverses the list of +available tdm devices to check if this tdm phy belongs to an already +registered tdm device. If a match is found, then this phy attaches itself to +that tdm device. Similarly the list of available tdm phys is traversed when a +new tdm device registers itself. + +Data handling: +============== +Some basic assumptions about data handling: + +1. As per standard voice rate of 8Khz or 8192Hz. Which means 8192 samples must +be sent every second. So if there are multiple clients sending voice data +over TDM interface the rate should be such that the individual samples +sent by them must be transmitted at 8 KHz. + +This is defined in the driver as + + #define CH_1_MS_FRAMES 8 + +2. Number of milliseconds at which TDM Rx interrupts occur +This is basically the time for which the TDM data is sent in one Tx or Rx +cycle of TDM controller hardware. In one DMA we send the data for 10ms. +This gives enough time so that no buffer overflow or under-run occurs for +transmit and receive respectively. + + #define NUM_MS 10 + +3. TDM has programmable slot length (8 bits or 16 bits). This can be configured by: + + #define CHANNEL_8BIT_LIN 0 /* 8 bit linear */ + #define CHANNEL_8BIT_ULAW 1 /* 8 bit Mu-law */ + #define CHANNEL_8BIT_ALAW 2 /* 8 bit A-law */ + #define CHANNEL_16BIT_LIN 3 /* 16 bit Linear */ + +depending on the type of sample. For example the sample could be 16 bit linear +or 8bit u-law encoded etc. Presently only word length of 16 is supported +which is the default configuration. + +4. Number of channels means the total number of channels per TDM port. +For example for E1 mode it will be 24, for T1 it will be 32, etc. +There can also be raw mode, where the use case is not E1 or T1. +Here the number of channels can be any number as per the use case. + +The whole framework follows a triple buffer approach to make sure that TDM data +is played continuously at the desired rate. + +Buffers Involved: +================= + +1.TDM driver or device buffers: +These buffers are the device level buffers. They contain the TDM data +which is transmitted/received on the TDM physical signals. As such these buffers must be +allocated from driver layer so that all the hardware requirements are met. +As an optimized design to remove extra memcopies, the client can +pass the data in the same buffers. But this is only true for full mode of +TDM. Where the user data can be straightaway passed to the hardware for +transmission. Although in other cases memcopy cannot be avoided, because +the framework layer will have to interleave the individual channels data to +create the TDM frame data buffer. The size of this buffer will be governed by + +For channelised mode: +The size of this buffer will be + +- number of channels +- number of slots per channel +- number of bytes per slot +- number of frames per ms +- number of ms + +For a channelised mode with single port the size of the device level buffer +will be: +channels * slots per channel * bytes per slot * frames per ms * number of ms +channels * 1 * NUM_BYTES_PER_SLOT * NUM_MS * CH_1_MS_FRAMES + +There will be 3 such buffers. + +2.Channel level buffers: +In case the TDM device is configured for multiport/multichannel the Framework +layer needs to maintain the data for each channel. Hence for each channel +opened a Buffer Descriptor ring of 3 BDs(see note below) is allocated both for +transmit and receive. The client reads from/writes to the buffers pointed by +these BD rings. + +The framework layer maintains a Data Process Tasklet per TDM +device which is scheduled from every Rx interrupt. The interrupt handling +periodicity is governed by the TDM data buffer size configured in the above +section. +The data tasklet when scheduled, will do Rx and Tx processing to copy +the data from/to the channel specific interleaved buffers. The TDM +controller will DMA the data which is copied in the interleaved buffers + or device level buffers. + +TDM framework provides the port level APIs and channel level APIs to the TDM +client drivers to send and receive the respective data on different TDM slots. + + +num of buffers = 3 + +TDM client1 TDM Client2 + +buf0------->buf1 buf0------->buf1 +^ | ^ | +| V | V +----buf2------ ------buf2---- + | | + | | + | | + V V +----------------------------------------- +| | +| DATA Tasklet | +| | +----------------------------------------- + | + | + V +----------------------------------------- +| TDM buffer interleaved * 3 | +----------------------------------------- + + +Not Implemented/Future work: +============================ +1. TDM client will use the default configuration which is done at init time and + is not configurable. In future this should be made configurable as per the + need of client. +2. The TDM framework still needs to be enhanced to configure the ports and their + attributes. Currently only single port channelised mode is supported. +3. Line control interface is not available in the framework presently. + Presently it offer very minimal kind of interface. +4. SLIC interface will be enhanced as per Zarlink Open source APIs in future. diff --git a/Documentation/tdm/tdm-summary.txt b/Documentation/tdm/tdm-summary.txt new file mode 100644 index 0000000..2788e7f --- /dev/null +++ b/Documentation/tdm/tdm-summary.txt @@ -0,0 +1,103 @@ +Time Division Multiplexing (TDM) +================================= + +TDM stands for Time Division Multiplexing. TDM is a type of digital or analog multiplexing in which two or more bit +streams or signals are transferred apparently simultaneously as sub-channels +in one communication channel, but are physically taking turns on the channel. + +The time domain is divided into several recurrent timeslots of fixed duration. +These timeslot are grouped together to form a channel. A sample byte or data +block of channel 1 is transmitted during timeslots allocated to channel 1, +channel 2 during timeslot for channel 2, etc. + +One TDM frame consists of multiple channels. After the last channel the cycle +starts all over again with a new frame, starting with the second sample, byte +or data block from channel 1, and so on. + +X----------TDM Frame 0-------------X------TDM Frame 1-----------------X +|----|----|----|----|----|----|----|----|----|----|----|----|----|----| +| 0 | 1 | 2 | 3 | 4 | ...| n | 0 | 1 | 2 | 3 | 4 | ...| n |... +|----|----|----|----|----|----|----|----|----|----|----|----|----|----| +<----> <----> +channel 0 channel 0 +--------------------------------------------------------------------> + Increasing Time + +Physical TDM interface +======================= + +Physically TDM interface is a serial full duplex interface designed to +communicate with variety of serial devices like industry standard framers, +codecs, other DSPs, and microprocessors. It is typically used to transfer +samples in a periodic manner. The TDM consists of independent transmitter and +receiver sections with independent clock generation and frame synchronization. + +External TDM signals are: +1. TDM_TCK: TDM Transmit clock +2. TDM_RCK: TDM Receive clock +3. TDM_TFS: TDM Tx frame sync to identify frame boundary +4. TDM_RFS: TDM Rx Frame sync to identify frame boundary +5. TDM_TD: TDM Tx data +6. TDM_RD: TDM Rx data + +TDM is generally used to simultaneously transmit periodic data for multiple +users. Common use cases would be to carry voice for various telephone +subscribers in the telephone networks. It is widely used to carry telephonic +data of various industry standards like E1/T1 data, etc. + +T1 Details +========== +T1 frame consists of 24 channels of 8 bits each plus one frame alignment bit. +So a T1 frame has a total of 24x8 + 1 = 193 bits. Since each T1 frame contains +one byte of voice data for each of 24 channels and the system needs to maintain +a data rate of 8000 samples/sec. This would require 8000 frames/sec to be sent, +yielding a data rate of 8000x193 bit/sec = 1.544 Mbps. + +E1 Details +=========== +E1 frame consists of 32 channels each of 8 bits. Thus having a total frame +length of 32x8 = 256 bits. Similar to the case of T1 it has to maintain a data +rate of 8000 frames/sec. Thus having a data rate of 8000 x 256 bits/sec = +2.048 Mbps. + +TDM use cases +============= + +With SLIC kind of devices +========================= +SLIC stands for Subscriber Line Interface Card. +Typically TDM systems consist of TDM controller and a line control device. + +The TDM controller interfaces to the line control device through TDM interface +which is digital TDM multiplexed data. + +The Line controller has the functionality to interface with the TDM controller +at one end and interface with the analog units at the other. For example if the +line control device is a SLIC kind of device. +The typical setup would be: + +|------------------| +| | +| | /-------\ |---------| +| TDM controller |/ TDM \ | SLIC |<--------> s-ch0 analog phone 1 +| |\ data / | |<--------> s-ch1 analog phone 2 +| | \-------/ |---------|<--------> s-ch2 analog phone 3 +| |<----digital----> +|------------------| + + + +Another use case (VoIP): +======================== + + Voice packets on network + |--------| |------| _________ |------| |------| +>----| |/---\| TDM | ( ) | TDM |/---\| |-----> +<----| SLIC |\---/| | ( n/w ) | |\---/| SLIC |-----< +>----| | |------| --------- |------| | |-----> + |--------| mux demux |------| + +In the above figure analog phones are connected to the hosts via SLICs. +The voice spoken on the phones is multiplexed converted into VoIP packets +and sent over network. At the rendering end the multiplexed data +is de-multiplexed and sent to respective listeners via SLIC.