[PATCH][1/3][RFC] Adding documentation for TDM
Poonam Aggrwal
poonam.aggrwal at freescale.com
Sat Mar 10 23:56:46 EST 2012
From: Sandeep Singh <Sandeep at freescale.com>
tdm-summary.txt contains general description about TDM.
tdm-framework.txt contains specific description of TDM framework.
Signed-off-by: Sandeep Singh <Sandeep at freescale.com>
Signed-off-by: Poonam Aggrwal <poonam.aggrwal at freescale.com>
---
Added the documentation to so that reviwers get the context.
Documentation/tdm/tdm-framework.txt | 257 +++++++++++++++++++++++++++++++++++
Documentation/tdm/tdm-summary.txt | 103 ++++++++++++++
2 files changed, 360 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..9f0ca36
--- /dev/null
+++ b/Documentation/tdm/tdm-framework.txt
@@ -0,0 +1,257 @@
+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.
+
+X----------TDM Frame 0-------------X------TDM Frame 1-----------------X
+|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
+| 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.
+5. TDM port: It can be seen as a virtual device exposed to a client. At a time
+ TDM port can work in one of the follwing configurations
+ full/fractional/E1/T1/raw.
+
+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.
+
+X----------TDM Frame 0-------------X------TDM Frame 1-----------------X
+|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
+| 0 | 1 | 2 | 3 | 4 | ...| n | 0 | 1 | 2 | 3 | 4 | ...| n |...
+|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
+<----><---> <----><--->
+ch0 ch1 ch0 ch1
+client0 client1
+
+TDM Subsystem Overview
+========================
+
+ |-----------------------|
+ |user mode TDM clients |
+ |-----------------------|
+ ||
+-------------------------------------------------------------------
+ tdm-dev.c ||
+ ||
+ || |------------------------|
+ client register | 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.
+
+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 8Kz.
+
+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 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.For channelised mode size of this buffer will be governed by:
+
+-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
+
+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 needs 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..d2e6eca
--- /dev/null
+++ b/Documentation/tdm/tdm-summary.txt
@@ -0,0 +1,103 @@
+Time-Division Multiplexing (TDM)
+=================================
+
+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
+=========================
+
+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 > <analog>
+|------------------|
+
+
+
+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.
--
1.5.6.5
More information about the Linuxppc-dev
mailing list