Patchwork [1/3,upstream] Adding documentation for TDM

login
register
mail settings
Submitter Sandeep Singh
Date July 23, 2012, 10:49 a.m.
Message ID <1343040588-16002-2-git-send-email-b37400@freescale.com>
Download mbox | patch
Permalink /patch/172624/
State Not Applicable
Headers show

Comments

Sandeep Singh - July 23, 2012, 10:49 a.m.
From: Sandeep Singh <Sandeep@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@freescale.com>
Signed-off-by: Poonam Aggrwal <poonam.aggrwal@freescale.com>
---
 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
David Laight - July 23, 2012, 12:32 p.m.
> +3. TDM has programmable slot length (8 bits or 16 bits). This can be
> +   configured by:
> +
> +	#define NUM_BYTES_PER_SLOT	8

I presume you meant NUM_BITS_PER_SLOT ?
These constants need name-space protection

> +or
> +	#define NUM_BYTES_PER_SLOT	16
> +
> +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.

For flexibility you need to allow for 8bit samples
being converted as:
1) 8bit raw ulaw or alaw data (unchanged from line).
2) 8bit raw data, bit reversed, any hdlc protocol
   is bit reversed from audio [1].
3) 8bit audio, converted from alaw to ulaw
4) 8bit audio, converted from ulaw to alaw
5) 16bit linear converted to/from alaw or ulaw
and on a per-timeslot basis.

[1] most hdlc stuff probably can't stand the 10ms
epochs though, so this is limited use for serious work.

	David
Aggrwal Poonam-B10812 - July 24, 2012, 3:12 p.m.
Thanks David for the comments.

Response Inline.

Regards
Poonam

> -----Original Message-----
> From: David Laight [mailto:David.Laight@ACULAB.COM]
> Sent: Monday, July 23, 2012 6:02 PM
> To: Singh Sandeep-B37400; linuxppc-dev@lists.ozlabs.org
> Cc: Singh Sandeep-B37400; Aggrwal Poonam-B10812
> Subject: RE: [1/3][PATCH][upstream]Adding documentation for TDM
> 
> > +3. TDM has programmable slot length (8 bits or 16 bits). This can be
> > +   configured by:
> > +
> > +	#define NUM_BYTES_PER_SLOT	8
> 
> I presume you meant NUM_BITS_PER_SLOT ?
> These constants need name-space protection
> 
> > +or
> > +	#define NUM_BYTES_PER_SLOT	16
> > +
This is a mistake, documentation patch not updated with the update design.
> > +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.
> 
> For flexibility you need to allow for 8bit samples being converted as:
> 1) 8bit raw ulaw or alaw data (unchanged from line).
> 2) 8bit raw data, bit reversed, any hdlc protocol
>    is bit reversed from audio [1].
> 3) 8bit audio, converted from alaw to ulaw
> 4) 8bit audio, converted from ulaw to alaw
> 5) 16bit linear converted to/from alaw or ulaw and on a per-timeslot
> basis.
I agree. That we only support very limited samples. But We can add this in second step once the basic framework is in.
Also right now the testing infrastructure we have, we won't be able to test all these scenarios.

> 
> [1] most hdlc stuff probably can't stand the 10ms epochs though, so this
> is limited use for serious work.
Right now the framework has been customized for voice. We can keep this parameter as a sysfs knob. Please suggest.

Regards
Poonam
> 
> 	David
> 
> 
>
David Laight - July 25, 2012, 8:44 a.m.
> > For flexibility you need to allow for 8bit samples being converted
as:
> > 1) 8bit raw ulaw or alaw data (unchanged from line).
> > 2) 8bit raw data, bit reversed, any hdlc protocol
> >    is bit reversed from audio [1].
> > 3) 8bit audio, converted from alaw to ulaw
> > 4) 8bit audio, converted from ulaw to alaw
> > 5) 16bit linear converted to/from alaw or ulaw and on a per-timeslot
> > basis.
> I agree. That we only support very limited samples. But We can add
this
> in second step once the basic framework is in.
> Also right now the testing infrastructure we have, we won't be able to
> test all these scenarios.

You probably ought to make the application request a specific
format - and error the unsupported ones.
That would make it easier to add support for other formats
later.

I also suspect that this 'framework' isn't that general!
We (as a company) use the TDM interface blocks on the MSC8101
and MSC8013 Starecore DSPs as well as some bespoke FPGA logic
(which will do ulaw<->alaw convertion).
The 'framework' would almost certainly be inappropriate
for both out hardware and software.

	David
Aggrwal Poonam-B10812 - July 25, 2012, 12:08 p.m.
> -----Original Message-----
> From: David Laight [mailto:David.Laight@ACULAB.COM]
> Sent: Wednesday, July 25, 2012 2:14 PM
> To: Aggrwal Poonam-B10812; Singh Sandeep-B37400; linuxppc-
> dev@lists.ozlabs.org
> Cc: Singh Sandeep-B37400
> Subject: RE: [1/3][PATCH][upstream]Adding documentation for TDM
> 
> > > For flexibility you need to allow for 8bit samples being converted
> as:
> > > 1) 8bit raw ulaw or alaw data (unchanged from line).
> > > 2) 8bit raw data, bit reversed, any hdlc protocol
> > >    is bit reversed from audio [1].
> > > 3) 8bit audio, converted from alaw to ulaw
> > > 4) 8bit audio, converted from ulaw to alaw
> > > 5) 16bit linear converted to/from alaw or ulaw and on a per-timeslot
> > > basis.
> > I agree. That we only support very limited samples. But We can add
> this
> > in second step once the basic framework is in.
> > Also right now the testing infrastructure we have, we won't be able to
> > test all these scenarios.
> 
> You probably ought to make the application request a specific format -
> and error the unsupported ones.
> That would make it easier to add support for other formats later.
David there is still configuration interface which needs to be added to the Framework.
This is mentioned in the documentation and patch also.
But we really need the core stuff which is handling the data get in and things will be added subsequently. 
> 
> I also suspect that this 'framework' isn't that general!
All the feedback welcome!
> We (as a company) use the TDM interface blocks on the MSC8101 and MSC8013
> Starecore DSPs as well as some bespoke FPGA logic (which will do ulaw<-
> >alaw convertion).
> The 'framework' would almost certainly be inappropriate for both out
> hardware and software.
Thanks a lot for the feedback. Can you please help to understand what is the scenario and how you use TDM. This will be a big help.
More generic the better.

Regards
Poonam
> 
> 	David
> 
> 
>

Patch

diff --git a/Documentation/tdm/tdm-framework.txt b/Documentation/tdm/tdm-framework.txt
new file mode 100644
index 0000000..b5a98bf
--- /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. TDM: Time Division Multiplexing.
+2. TDM channel: The channel is the smallest entity on which all the TDM read/
+   write operations will occur. Technically each channel maps 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 adapter or Adapter: Refers to an instance of TDM controller/device on
+   the system.
+4. 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  |...
+|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
+<----><--->				   <---->
+ch 0	ch1			   ch 0
+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:
+
+	#define NUM_BYTES_PER_SLOT	8
+or
+	#define NUM_BYTES_PER_SLOT	16
+
+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 channels * 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 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..f010f76
--- /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
+=========================
+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---->     <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.