Skip to contentSkip to conversation

Adding Documentation for TDM

PATCH New Sandeep Singh 1 participant 4 messages Mar 5, 2013 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/4 Adding Documentation for TDM

tdm-summary.txt contains general description about TDM. tdm-framework.txt contains specific description of TDM framework.

---
 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
Documentation/tdm/tdm-framework.txt new file +264 -0
new file mode 100644
index 0000000..e8704a4
@@ -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.
Documentation/tdm/tdm-summary.txt new file +103 -0

103 lines not on this page · raw message

Signature · 1 line
1.7.6.GIT
#1 lore raw

PATCH v2 2/4 TDM Framework

TDM Framework is an attempt to provide a platform independent layer which can offer a standard interface for TDM access to different client modules. Beneath, the framework layer can house different types of TDM drivers to handle various TDM devices, the hardware intricacies of the devices being completely taken care by TDM drivers.

This framework layer will allow any type of TDM device to hook with it. For example Freescale controller as on MPC8315, UCC based TDM controller, etc

The main functions of this Framework are:
- provides interface to TDM clients to access TDM functionalities.
- provides standard interface for TDM drivers to hook with the framework.
- provides standard interface for line control devices to hook with the framework.
- handles various data handling stuff and buffer management.

Presently the framework supports only Single Port channelised mode.
Also the configurability options are limited which will be extended later on.
Only kernel mode TDM clients are supported currently. Support for User mode clients will be added later.

---
 drivers/Kconfig                 |    1 +
 drivers/Makefile                |    1 +
 drivers/tdm/Kconfig             |   25 +
 drivers/tdm/Makefile            |    8 +
 drivers/tdm/tdm-core.c          | 1198 +++++++++++++++++++++++++++++++++++++++
 include/linux/mod_devicetable.h |   11 +
 include/linux/tdm.h             |  379 +++++++++++++
 7 files changed, 1623 insertions(+), 0 deletions(-)
 create mode 100644 drivers/tdm/Kconfig
 create mode 100644 drivers/tdm/Makefile
 create mode 100644 drivers/tdm/tdm-core.c
 create mode 100644 include/linux/tdm.h
drivers/Kconfig +1 -0
index f5fb072..56a7707 100644
@@ -158,4 +158,5 @@ source "drivers/irqchip/Kconfig"
 
 source "drivers/ipack/Kconfig"
 
+source "drivers/tdm/Kconfig"
 endmenu
drivers/Makefile +1 -0
index 7863b9f..2f8f130 100644
@@ -112,6 +112,7 @@ obj-$(CONFIG_INFINIBAND)	+= infiniband/
 obj-$(CONFIG_SGI_SN)		+= sn/
 obj-y				+= firmware/
 obj-$(CONFIG_CRYPTO)		+= crypto/
+obj-$(CONFIG_TDM)		+= tdm/
 obj-$(CONFIG_SUPERH)		+= sh/
 obj-$(CONFIG_ARCH_SHMOBILE)	+= sh/
 ifndef CONFIG_ARCH_USES_GETTIMEOFFSET
drivers/tdm/Kconfig new file +25 -0
new file mode 100644
index 0000000..8db2b05
@@ -0,0 +1,25 @@
+#
+# TDM subsystem configuration
+#
+
+menuconfig TDM
+	tristate "TDM support"
+	---help---
+	  More information is contained in the directory <file:Documentation/tdm/>,
+	  especially in the file called "summary" there.
+	  If you want TDM support, you should say Y here and also to the
+	  specific driver for your bus adapter(s) below.
+
+	  This TDM support can also be built as a module.  If so, the module
+	  will be called tdm-core.
+
+if TDM
+
+config TDM_DEBUG_CORE
+	bool "TDM Core debugging messages"
+	help
+	  Say Y here if you want the TDM core to produce a bunch of debug
+	  messages to the system log.  Select this if you are having a
+	  problem with TDM support and want to see more of what is going on.
+
+endif # TDM
drivers/tdm/Makefile new file +8 -0
new file mode 100644
index 0000000..5569616
@@ -0,0 +1,8 @@
+#
+# Makefile for the TDM core.
+#
+
+obj-$(CONFIG_TDM)		+= tdm-core.o
+ifeq ($(CONFIG_TDM_DEBUG_CORE),y)
+EXTRA_CFLAGS += -DDEBUG
+endif
drivers/tdm/tdm-core.c new file +1198 -0

1,198 lines not on this page · raw message

include/linux/mod_devicetable.h +11 -0
index fed3def..b8214f3 100644
@@ -444,6 +444,17 @@ struct i2c_device_id {
 			__attribute__((aligned(sizeof(kernel_ulong_t))));
 };
 
+/* tdm */
+
+#define TDM_NAME_SIZE   20
+#define TDM_MODULE_PREFIX "tdm:"
+
+struct tdm_device_id {
+	char name[TDM_NAME_SIZE];
+	kernel_ulong_t driver_data      /* Data private to the driver */
+			__attribute__((aligned(sizeof(kernel_ulong_t))));
+};
+
 /* spi */
 
 #define SPI_NAME_SIZE	32
include/linux/tdm.h new file +379 -0

379 lines not on this page · raw message

Signature · 1 line
1.7.6.GIT
#2 lore raw

PATCH v2 3/4 Added TDM device support and Freescale Starlite driver

In reply to Sandeep Singh

Freescale TDM controller consists of a TDM module supporting 128 channels running at up to 50 Mbps with 8-bit and 16-bit word size. The TDM bus connects gluelessly to most T1/E1 frames as well as to common buses such as the H.110, SCAS, and MVIP. TDM also supports an I2S mode. The TDM module operates in independent or shared mode when receiving or transmitting data.

This controller is available on MPC8315, P1010, P1020, P1022 and P1024 Freescale SOCs.

The driver registers itself with the TDM Framework & provides TDM functionality to the client modules.

In its present form this driver supports only channelised mode.

---
 drivers/tdm/Kconfig          |    1 +
 drivers/tdm/Makefile         |    2 +-
 drivers/tdm/device/Kconfig   |   15 +
 drivers/tdm/device/Makefile  |    9 +
 drivers/tdm/device/tdm_fsl.c |  916 ++++++++++++++++++++++++++++++++++++++++++
 drivers/tdm/device/tdm_fsl.h |  444 ++++++++++++++++++++
 6 files changed, 1386 insertions(+), 1 deletions(-)
 create mode 100644 drivers/tdm/device/Kconfig
 create mode 100644 drivers/tdm/device/Makefile
 create mode 100644 drivers/tdm/device/tdm_fsl.c
 create mode 100644 drivers/tdm/device/tdm_fsl.h
drivers/tdm/Kconfig +1 -0
index 8db2b05..87d6929 100644
@@ -22,4 +22,5 @@ config TDM_DEBUG_CORE
 	  messages to the system log.  Select this if you are having a
 	  problem with TDM support and want to see more of what is going on.
 
+source drivers/tdm/device/Kconfig
 endif # TDM
drivers/tdm/Makefile +1 -1
index 5569616..347d3f7 100644
@@ -2,7 +2,7 @@
 # Makefile for the TDM core.
 #
 
-obj-$(CONFIG_TDM)		+= tdm-core.o
+obj-$(CONFIG_TDM)		+= tdm-core.o device/
 ifeq ($(CONFIG_TDM_DEBUG_CORE),y)
 EXTRA_CFLAGS += -DDEBUG
 endif
drivers/tdm/device/Kconfig new file +15 -0
new file mode 100644
index 0000000..9fd1b06
@@ -0,0 +1,15 @@
+#
+# TDM device configuration
+#
+
+menu "TDM Device support"
+
+config TDM_FSL
+        tristate "Driver for Freescale TDM controller"
+        depends on FSL_SOC
+        ---help---
+          This is a driver for Freescale TDM controller. The controller
+          is found in various Freescale SOCs viz MPC8315, P1020. The TDM driver
+          basically multiplexes and demultiplexes data from different channels.
+          The TDM can interface SLIC kind of devices.
+endmenu
drivers/tdm/device/Makefile new file +9 -0
new file mode 100644
index 0000000..4156d7f
@@ -0,0 +1,9 @@
+#
+# Makefile for the TDM device drivers.
+#
+
+obj-y	+= tdm_fsl.o
+
+#ifeq ($(CONFIG_TDM_DEBUG_BUS),y)
+#EXTRA_CFLAGS += -DDEBUG
+#endif
drivers/tdm/device/tdm_fsl.c new file +916 -0

916 lines not on this page · raw message

drivers/tdm/device/tdm_fsl.h new file +444 -0

444 lines not on this page · raw message

Signature · 1 line
1.7.6.GIT
#3 lore raw

PATCH v2 4/4 Basic configuration module for Le88266 Zarlink SLIC

In reply to Sandeep Singh

- Basic driver which does minimum intialization of the Le88266 SLIC device.
- The code was originally borrowed from Zarlink driver implementation.
- It is not full fledged SLIC driver code, it just does basic initialization which is required to setup a voice data path between channels. This is just enough to test and demonstrate TDM functionality on Freescale platforms using TDM Test Module.
- For full fledged VoIP type of use case proper SLIC driver will be required which handles all the functionalities of the device.
- Going forward this driver will be replaced by Opoen source Zarlink APIs.

---
 drivers/tdm/Kconfig                  |    1 +
 drivers/tdm/Makefile                 |    2 +-
 drivers/tdm/line_ctrl/Kconfig        |   12 +
 drivers/tdm/line_ctrl/Makefile       |    5 +
 drivers/tdm/line_ctrl/slic_zarlink.c |  715 ++++++++++++++++++++++++++++++++++
 drivers/tdm/line_ctrl/slic_zarlink.h |  131 +++++++
 6 files changed, 865 insertions(+), 1 deletions(-)
 create mode 100644 drivers/tdm/line_ctrl/Kconfig
 create mode 100644 drivers/tdm/line_ctrl/Makefile
 create mode 100644 drivers/tdm/line_ctrl/slic_zarlink.c
 create mode 100644 drivers/tdm/line_ctrl/slic_zarlink.h
drivers/tdm/Kconfig +1 -0
index f430adc..434ad6e 100644
@@ -24,4 +24,5 @@ config TDM_DEBUG_CORE
 
 source drivers/tdm/test/Kconfig
 source drivers/tdm/device/Kconfig
+source drivers/tdm/line_ctrl/Kconfig
 endif # TDM
drivers/tdm/Makefile +1 -1
index d73fbbd..ea66fff 100644
@@ -2,7 +2,7 @@
 # Makefile for the TDM core.
 #
 
-obj-$(CONFIG_TDM)		+= tdm-core.o device/
+obj-$(CONFIG_TDM)		+= tdm-core.o device/ line_ctrl/
 obj-$(CONFIG_TDM_TEST)		+= test/
 ifeq ($(CONFIG_TDM_DEBUG_CORE),y)
 EXTRA_CFLAGS += -DDEBUG
drivers/tdm/line_ctrl/Kconfig new file +12 -0
new file mode 100644
index 0000000..e7421b9
@@ -0,0 +1,12 @@
+#
+# TDM line control driver config file
+#
+
+menu "Line Control Devices"
+
+config SLIC_ZARLINK
+	tristate "Zarlink Slic intialization Module"
+		default n
+		---help---
+		  This module initialize and configure the zarlink slic
+endmenu
drivers/tdm/line_ctrl/Makefile new file +5 -0
new file mode 100644
index 0000000..91e8916
@@ -0,0 +1,5 @@
+#
+# Makefile for the TDM line control drivers.
+#
+
+obj-y		+= slic_zarlink.o
drivers/tdm/line_ctrl/slic_zarlink.c new file +715 -0

715 lines not on this page · raw message

drivers/tdm/line_ctrl/slic_zarlink.h new file +131 -0

131 lines not on this page · raw message

Signature · 1 line
1.7.6.GIT