From: Sandeep Singh <sand...@freescale.com> tdm-summary.txt contains general description about TDM. tdm-framework.txt contains specific description of TDM framework.
Signed-off-by: Sandeep Singh <sand...@freescale.com> Signed-off-by: Poonam Aggrwal <poonam.aggr...@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 _______________________________________________ Linuxppc-dev mailing list Linuxppc-dev@lists.ozlabs.org https://lists.ozlabs.org/listinfo/linuxppc-dev
