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----> <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.