631 lines
24 KiB
Plaintext
631 lines
24 KiB
Plaintext
Introduction
|
|
============
|
|
|
|
The Serial Mux (SMUX) is a TTY Line Discipline that multiplexes
|
|
multiple logical channels onto a single TTY serial channel. The
|
|
logical channels are exposed through a kernel API.
|
|
|
|
Companion adaptation drivers use the kernel API to expose logical
|
|
channels as character devices (SMUX CTL - smux_ctl.c) to the user-space
|
|
and as net devices (SMUX RMNET - msm_rmnet_smux.c) to the TCP/IP stack.
|
|
|
|
Power control calls are supported to the physical serial driver to
|
|
optimize power usage.
|
|
|
|
|
|
Software description
|
|
====================
|
|
|
|
The Serial Mux driver will be similar in design to the SDIO DMUX and
|
|
BAM DMUX drivers and will use the same multiplexing protocol with
|
|
additional commands to support inactivity timeouts along with
|
|
power-down and wake-up handshaking. Companion adaptation drivers will
|
|
support data-plane traffic through TCP/IP (SMUX_RMNET) and control
|
|
plane traffic through SMUX_CTL.
|
|
|
|
|
|
ttyHS0 RMNET[0..N] smuxctl[0..M]
|
|
| | |
|
|
| | |
|
|
| ------------------ -------------------
|
|
| | IP Framework | | VFS Framework |
|
|
| ------------------ -------------------
|
|
| | | | |
|
|
| | | | |
|
|
| ------- ------- ------- -------
|
|
| | Rmnet | | Rmnet | | CDEV | | CDEV |
|
|
| | Dev 0 |...| Dev N | | Dev 0 |...| Dev M |
|
|
| --------------------- --------------------- -------------
|
|
| | | | | | Other |
|
|
| | msm_rmnet_smux | | smux_ctl | | Kernel-only |
|
|
| | | | | | Clients |
|
|
| --------------------- --------------------- -------------
|
|
| | | | | |
|
|
| | | | | |
|
|
| | | | | |
|
|
| | | | | |
|
|
| ---------------------------------------------------
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
--------------- --------------------
|
|
| | | |
|
|
| TTY Framework | <- Line Discipline -> | SMUX |
|
|
| | | |
|
|
--------------- --------------------
|
|
| |
|
|
| |
|
|
--------------- |
|
|
| | |
|
|
| HS UART |<---------- Power API -----------
|
|
| |
|
|
---------------
|
|
|
|
|
V
|
|
To Remote System
|
|
|
|
|
|
Each logical channel will contain package management structures
|
|
including a watermark to ensure fair usage of the physical layer by
|
|
competing logical channels. All data for logical channels will be
|
|
processed in FIFO order.
|
|
|
|
Once data has been queued with SMUX, processing, copying of data, and
|
|
notification to clients will be done using a combination of the TTY
|
|
framework notification context and a workqueue. The lifetime of all
|
|
buffers is controlled by the clients with SMUX taking temporary
|
|
ownership of the buffers for read and write operations.
|
|
|
|
The physical transport is assumed to be perfect and all errors will be
|
|
handled by notifying the client of the failure. Watermark support and
|
|
round-robin scheduling ensure that individual logical channels do not
|
|
starve other logical channels.
|
|
|
|
Data stalls caused by failure of the remote system are handled by
|
|
Subsystem Restart. The restart logic will notify clients of the
|
|
failure and all read and write buffers will be returned to the client
|
|
with an error notification.
|
|
|
|
Design
|
|
======
|
|
|
|
The goals for SMUX are to:
|
|
1) multiplex multiple logical channels into a single physical
|
|
channel
|
|
2) support a kernel API
|
|
3) provide power control of the physical layer
|
|
|
|
In addition, the companion adapter modules have the goals:
|
|
1) support userspace character-device clients (smux_ctl)
|
|
2) support net devices through the TCP/IP stack (msm_rmnet_smux)
|
|
|
|
Alternate designs consider including 3GPP 27.010 MUX protocol
|
|
implementations and existing SDIO CMUX/DMUX implementations.
|
|
|
|
The 3GPP 27.010 MUX protocol as implemented in both n_gsm.c and OpenEZX
|
|
looked promising at first glance. However, upon further inspection,
|
|
the implementations did not fully implement the power-control portions
|
|
of the 27.010 MUX protocol. They also did not support kernel clients
|
|
as they were designed to work only with userspace through TTY devices.
|
|
The code was reviewed to determine the effort to add power-control
|
|
signaling to the physical transport driver and to add a kernel API, but
|
|
it was deemed that adding the API to support both of these behaviors
|
|
would be difficult to do in a generic way such that it would be
|
|
accepted by the upstream community.
|
|
|
|
The SDIO CMUX/DMUX drivers do not have power control in them and the
|
|
CMUX and DMUX drivers both require a separate physical channel. To use
|
|
them, we would need to create an additional mux layer that would sit
|
|
between CMUX/DMUX and the HS UART driver which would add another MUX
|
|
header.
|
|
|
|
Design - MUX Protocol
|
|
=====================
|
|
The MUX packet consists of a header (detailed below) and a payload.
|
|
All values are in little-endian format and all reserved fields are set
|
|
to zero unless otherwise mentioned in the individual command
|
|
descriptions.
|
|
|
|
Invalid commands and malformed commands will be logged to the kernel log
|
|
as an error and ignored.
|
|
|
|
-----------------------------------------
|
|
|31 24| 16| 8| 0|
|
|
|----------|---------|----------|---------|
|
|
| Magic Number | Flags | CMD |
|
|
|----------|---------|----------|---------|
|
|
| Pad Len | LCID | Packet Length (N) |
|
|
|-----------------------------------------|
|
|
| Data Payload (0..N bytes) |
|
|
|-----------------------------------------|
|
|
| Pad Data (0..Pad Len bytes) |
|
|
-----------------------------------------
|
|
|
|
Field definitions:
|
|
* Magic Number - always 0x33FC
|
|
* Flags - flags for individual commands
|
|
* CMD - SMUX command
|
|
* Pad Len - Padding in bytes at the end of the payload
|
|
* LCID - Logical channel ID
|
|
* Packet Length - Length of the data payload in bytes
|
|
|
|
Commands
|
|
0x0 - Data
|
|
0x1 - Open Logical Channel
|
|
0x2 - Close Logical Channel
|
|
0x3 - Status
|
|
0x4 - Power Control
|
|
|
|
Data Command
|
|
------------
|
|
The Data command sends data on an already fully-opened logical channel.
|
|
|
|
Flags:
|
|
* Bits 0:7 - Reserved
|
|
|
|
Open Logical Channel Command
|
|
----------------------------
|
|
The Open command is a request to open a logical channel. Each channel
|
|
will have a local and remote open flag. The remote open flag will be
|
|
set to open when receiving an open command and responding with an open
|
|
ACK. The local open flag is set to open when sending an open command
|
|
and receiving an ACK.
|
|
|
|
Remote Side | Local Side
|
|
|
|
|
SMUX Client SMUX SMUX SMUX Client
|
|
| | | |
|
|
| Open | | |
|
|
|--------->| | |
|
|
| | Open Logical Channel | |
|
|
| |---------------------->| |
|
|
| | |--- |
|
|
| | | | Set Remote Open |
|
|
| | |<-- |
|
|
| | Open ACK | |
|
|
| |<----------------------| |
|
|
| |--- | |
|
|
| | | Set Local Open | |
|
|
| |<-- | |
|
|
| ... ... ...
|
|
| | | msm_smux_open() |
|
|
| | |<-----------------------|
|
|
| | Open Logical Channel | |
|
|
| |<----------------------| |
|
|
| | | |
|
|
| |--- | |
|
|
| | | Set Remote Open | |
|
|
| |<-- | |
|
|
| | Open ACK | |
|
|
| |---------------------->| |
|
|
| | |--- |
|
|
| | | | Set Local Open |
|
|
| | |<-- |
|
|
| | | notify(SMUX_CONNECTED) |
|
|
| | |----------------------->|
|
|
|
|
|
|
Logical channel is now fully open and can receive
|
|
and transmit data.
|
|
|
|
No data shall be transmitted over the physical link for the logical
|
|
channel unless the channel is open.
|
|
|
|
Flags:
|
|
* Bit 0 - 1 = ACK
|
|
* Bit 1 - Power Collapse Enable
|
|
* Bit 2 - Remote Loopback Enable
|
|
* Bits 3:7 - Reserved
|
|
|
|
Power Collapse Enable (bit 1) enables power-collapse handshaking when
|
|
processing an open command. The first logical channel open command
|
|
received from the remote side will set the global power control state
|
|
and all subsequent open commands should use the same value of the Power
|
|
Collapse bit. The value of this bit can be changed during runtime by
|
|
closing all logical channels and then re-opening them with the new
|
|
global state.
|
|
|
|
If the protocol stack does not support power collapse and it receives
|
|
an open command with the Power Collapse Enable bit set, then it
|
|
shall respond with an open command with the Power Collapse Enable bit
|
|
cleared.
|
|
|
|
If Power Collapse is disabled, then Power Control Commands should not
|
|
be sent.
|
|
|
|
Remote Loopback Enable (bit 2) enables loopback support when data is
|
|
received from the remote side. In this case, SMUX should echo the
|
|
received data packet back to the sender.
|
|
|
|
Close Logical Channel Command
|
|
-----------------------------
|
|
The Close command closes the logical channel and updates the internal
|
|
open state flags. The remote open flag will be set to closed when
|
|
receiving a close command and responding with an close ACK. The local
|
|
open flag is set to closed when sending a close command and receiving an
|
|
ACK.
|
|
|
|
No data shall be transmitted over the physical link for the logical
|
|
channel after receiving a close command and responding with the close
|
|
ACK.
|
|
|
|
Flags:
|
|
* Bit 0 - ACK (when set to 1)
|
|
* Bits 1:7 - Reserved
|
|
|
|
|
|
Status Command
|
|
--------------
|
|
The Status Command updates the channel status signals which include four
|
|
ITU v.24 status bits in the lower nibble of the flags field along with a
|
|
logical channel flow-control signal. The v.24 signals are pass-through
|
|
and do not affect the state of SMUX.
|
|
|
|
The Logical Channel Flow Control bit will disable TX on the logical
|
|
channel when set and send a flow-control notification to the logical
|
|
channel client. Any further attempts to transmit will result in an
|
|
error return code.
|
|
|
|
Flags:
|
|
* Bit 0 - RTC (DTR/DSR)
|
|
* Bit 1 - RTR (RTS/CTS)
|
|
* Bit 2 - RI
|
|
* Bit 3 - DCD
|
|
* Bit 4 - Logical Channel Flow Control
|
|
* Bits 5:7 - Reserved
|
|
|
|
|
|
Power Control Command
|
|
---------------------
|
|
The physical layer requires a variable amount of time to wakeup from
|
|
power collapse, reconfigure the hardware, and start processing data.
|
|
Data may be lost until the wakeup has been completed. Because of this,
|
|
a character-based wakeup method will be used to ensure that the remote
|
|
side is active and ready before sending SMUX commands.
|
|
|
|
If the remote side has previously requested power-down (boot-up state),
|
|
then a wakeup request character is sent at periodic intervals (1 ms or
|
|
8 character-widths, whichever is larger) until a wakeup-acknowledge character
|
|
has been received. Normal transmit operations can then be performed. Once an
|
|
activity timeout occurs, then a sleep vote should be sent to the remote side to
|
|
let it know that the channel is no longer needed. The remote side should
|
|
respond with an ACK.
|
|
|
|
The following state diagram shows the full sequence of power state transitions.
|
|
This state machine is identical on both the local and remote sides. The states
|
|
marked "(internal)" are transitional states used in this driver that are not
|
|
part of the power states tracked by the remote side. The edges are labeled
|
|
using the format CONDITION:ACTION where condition is the guard condition that
|
|
must be true for the edge to be taken and ACTION is the action that will be
|
|
taken.
|
|
|
|
+--------------+ RX Sleep ACK || RX Sleep Request
|
|
:Flush and power-down | Powering |<---------+
|
|
UART +---------+ Down Flush | |
|
|
| | (internal) | |
|
|
| +--------------+ |
|
|
| ^ |
|
|
| | +-------+------+
|
|
v | | | |
|
|
+--------------+ | | Powering |
|
|
| | | | Down |<-----+
|
|
Init --->| OFF | | | | |
|
|
| |------+ | +--------------+ |
|
|
| | | | |
|
|
+------+-------+ | | TX Sleep Request
|
|
| | | Complete
|
|
| | | |
|
|
Data ready to send | | |
|
|
:TX Wakeup Request | |RX Sleep Request |
|
|
| | |:TX Sleep ACK |
|
|
| | +------------+ +-------+------+
|
|
| | | | Turning Off^|
|
|
| | | | Flush |
|
|
| | | | (internal) |
|
|
| |RX Wakeup Request | +--------------+
|
|
| |:TX Wakeup ACK | ^
|
|
| | | |
|
|
| | | Inactivity Timeout
|
|
| +--------------+ | :TX Sleep Request
|
|
| | | |
|
|
v v | |
|
|
+--------------+ RX Wakeup ACK +-------+------+ |
|
|
| +------------------>| UP |+-----+
|
|
| Powering | | |
|
|
| Up +------------------>| Packet TX/RX |
|
|
+----->| | RX Wakeup Request | is now active|<------+
|
|
| +--+-----------+ :TX Wakeup ACK +----------+---+ |
|
|
| | | |
|
|
+---------+ +-----------+
|
|
Wakeup Request Timeout RX Wakeup Request
|
|
:TX Wakeup Request :TX Wakeup ACK
|
|
|
|
|
|
In-band wakeup bytes:
|
|
* 0xfd - Wakeup Request
|
|
* 0xfe - Wakeup Acknowledge
|
|
|
|
Flags:
|
|
* Bit 0 - ACK (when set to 1)
|
|
* Bit 1 - 1 = Sleep Request
|
|
* Bits 2:7 - Reserved
|
|
|
|
Initial SMUX State
|
|
------------------
|
|
The boot-up state of SMUX is in power-disabled mode and all logical
|
|
channels closed. Before sending any commands to open logical channels,
|
|
the remote SMUX must be woken up.
|
|
|
|
Power Management
|
|
================
|
|
|
|
Power management will consist of wakeup and shutdown control of the
|
|
physical layer based upon an activity timeout. Wakelocks will be
|
|
utilized to prevent the system from going to sleep while the transport
|
|
is active. The activity timeout is anticipated to be 500 ms, but this
|
|
is subject to tuning to meet power and performance specifications.
|
|
|
|
SMP/multi-core
|
|
==============
|
|
|
|
Locking and synchronization will be done using mutexes or spinlocks
|
|
where appropriate. The software will be structured such that locking
|
|
can be kept to a minimum by only locking when items are added and
|
|
removed from lists.
|
|
|
|
Security
|
|
========
|
|
|
|
No new security issues are anticipated as communication with userspace
|
|
is done through the existing TCP/IP and CDEV frameworks.
|
|
|
|
Performance
|
|
===========
|
|
|
|
The throughput requirements for this design are on the order of 250Kbps
|
|
so throughput concerns are not expected to be an issue. However, in
|
|
the hope that this driver can be leveraged in the future instead of
|
|
writing yet another multiplexing layer, performance will be considered
|
|
when making design decisions.
|
|
|
|
Interface
|
|
=========
|
|
|
|
The kernel API consists of commands to read and write data, vote for
|
|
power, and verify the state of the logical channels.
|
|
|
|
|
|
Open
|
|
----
|
|
int msm_smux_open(uint32_t lcid, void *priv,
|
|
void (*notify)(void *priv, int event_type, void *metadata),
|
|
int (*get_rx_buffer)(void *priv, void **pkt_priv,
|
|
void **buffer, int size))
|
|
|
|
Open a logical channel. The channel will be first opened locally and
|
|
an open command will be sent to the remote processor. Once the remote
|
|
processor sends an open command, then the port will be fully open and
|
|
ready for data operations -- the client will be notified with an
|
|
SMUX_CONNECTED notification.
|
|
|
|
For receive notifications, the driver will read the SMUX header into
|
|
temporary storage and then when the logical channel and size are both
|
|
known, the driver will call the get_rx_buffer() function to request a
|
|
buffer for the data. The client should return 0 upon success or < 0
|
|
using standard Linux error codes if an error occurred. If the error
|
|
code is EAGAIN, then the call to get_rx_buffer() will be retried once,
|
|
otherwise the data will be discarded by the driver and a kernel error
|
|
message logged.
|
|
|
|
Once the receive data has been processed, the notify() function will be
|
|
called with metadata pointing to an instance of struct smux_meta_read
|
|
and the event type will either be SMUX_READ_DONE for successful cases or
|
|
SMUX_READ_FAIL for failure cases.
|
|
|
|
/*
|
|
* Notification events that are passed to the notify() function.
|
|
*
|
|
* If the @metadata argument in the notifier is non-null, then it will
|
|
* point to the associated struct smux_meta_* structure.
|
|
*/
|
|
enum {
|
|
SMUX_CONNECTED, /* @metadata is null */
|
|
SMUX_DISCONNECTED,
|
|
SMUX_READ_DONE,
|
|
SMUX_READ_FAIL,
|
|
SMUX_WRITE_DONE,
|
|
SMUX_WRITE_FAIL,
|
|
SMUX_TIOCM_UPDATE,
|
|
SMUX_LOW_WM_HIT, /* @metadata is NULL */
|
|
SMUX_HIGH_WM_HIT, /* @metadata is NULL */
|
|
};
|
|
|
|
/*
|
|
* Metadata for SMUX_READ_DONE/SMUX_READ_FAIL notification
|
|
*
|
|
* @pkt_priv: Packet-specific private data
|
|
* @buffer: Buffer pointer passed into msm_smux_write
|
|
* @len: Buffer length passed into msm_smux_write
|
|
*/
|
|
struct smux_meta_read {
|
|
void *pkt_priv;
|
|
void *buffer;
|
|
int len;
|
|
};
|
|
|
|
Close
|
|
-----
|
|
int msm_smux_close(uint32_t lcid)
|
|
|
|
Closes a logical channel locally and sends a close command to the
|
|
remote host.
|
|
|
|
If there is pending transmit or receive data, then SMUX_WRITE_FAIL and
|
|
SMUX_READ_FAIL notifications will be made to return ownership of the
|
|
buffers to the client.
|
|
|
|
Once the remote side of the port has been closed, the notify function
|
|
will be called with the event SMUX_DISCONNECTED and metadata pointing
|
|
to a struct smux_meta_disconnected structure. After this point, no
|
|
further notifications will be performed.
|
|
|
|
/*
|
|
* Metadata for SMUX_DISCONNECTED notification
|
|
*
|
|
* @is_ssr: Disconnect caused by subsystem restart
|
|
*/
|
|
struct smux_meta_disconnected {
|
|
int is_ssr;
|
|
};
|
|
|
|
|
|
Write
|
|
-----
|
|
int msm_smux_write(uint32_t lcid, void *pkt_priv, void *data, int len)
|
|
|
|
Queues data for transmit. Once the data has been transmitted, the
|
|
SMUX_WRITE_DONE or SMUX_WRITE_FAIL notifications will be sent with
|
|
metadata pointing to an instance of struct smux_meta_write.
|
|
|
|
If the high watermark has been exceeded, then further writes will
|
|
return -EAGAIN.
|
|
|
|
Data may be written as soon as the local side of the port has been
|
|
opened, but the data will not be transmitted until the channel has been
|
|
fully opened and the SMUX_CONNECTED event has been sent.
|
|
|
|
/*
|
|
* Metadata for SMUX_WRITE_DONE/SMUX_WRITE_FAIL notification
|
|
*
|
|
* @pkt_priv: Packet-specific private data
|
|
* @buffer: Buffer pointer returned by get_rx_buffer()
|
|
* @len: Buffer length returned by get_rx_buffer()
|
|
*/
|
|
struct smux_meta_write {
|
|
void *pkt_priv;
|
|
void *buffer;
|
|
int len;
|
|
};
|
|
|
|
Watermark
|
|
---------
|
|
int msm_smux_is_ch_full(uint32_t lcid)
|
|
int msm_smux_is_ch_low(uint32_t lcid)
|
|
|
|
A channel watermark is used to keep individual clients from using
|
|
excessive internal resources. The client may call
|
|
msm_smux_is_ch_full() after every msm_smux_write() operation and if the
|
|
watermark is high, it should not queue any more packets for
|
|
transmission. As an alternative, the client may base this decision
|
|
upon receiving an SMUX_HIGH_WM_HIT notification.
|
|
|
|
Likewise, the client may call msm_smux_is_ch_low() after every
|
|
SMUX_WRITE_DONE or SMUX_WRITE_FAIL notification and if the watermark is
|
|
low, then new transmit operations can be started. As an alternative,
|
|
the client may base this decision upon receiving an SMUX_LOW_WM_HIT
|
|
notification.
|
|
|
|
Control Signals
|
|
---------------
|
|
long msm_smux_tiocm_get(uint32_t lcid)
|
|
long msm_smux_tiocm_set(uint32_t lcid, uint32_t set, uint32_t clear)
|
|
|
|
The TIOCM bits do not affect the SMUX internal state as they are
|
|
pass-through for the clients. The client can receive notifications of
|
|
state changes through the SMUX_TIOCM_UPDATE command.
|
|
|
|
See the "Status Command" section for details on the TIOCM bits.
|
|
|
|
/*
|
|
* Metadata for SMUX_TIOCM_UPDATE notification
|
|
*
|
|
* @previous: Previous TIOCM state
|
|
* @current: Current TIOCM state
|
|
*
|
|
*/
|
|
struct smux_meta_tiocm {
|
|
uint32_t previous;
|
|
uint32_t current;
|
|
};
|
|
|
|
Subsystem Restart
|
|
-----------------
|
|
Subsystem restart is handled by sending a disconnect notification
|
|
followed by sending read and write fail notifications to each client.
|
|
This returns ownership of the read and write buffers to the clients for
|
|
client-appropriate handling.
|
|
|
|
The sequence of notifications shall be:
|
|
1) SMUX_DISCONNECTED notification with @metadata->is_ssr == 1
|
|
2) SMUX_WRITE_FAIL for each packet in TX queue
|
|
3) SMUX_READ_FAIL for any RX packet in progress
|
|
|
|
After the completion of the sequence, the client should call msm_smux_close()
|
|
followed by a call to msm_smux_open() to re-open the port.
|
|
|
|
|
|
Debug / Testing
|
|
---------------
|
|
|
|
Several debugfs nodes will be exported under the n_gsm directory for
|
|
testing and debugging.
|
|
* tbl - prints table of logical channels
|
|
* stats - prints transfer statistics
|
|
* enable_local_loopback - echo LCID to enable loopback
|
|
* disable_local_loopback - echo LCID to enable loopback
|
|
* enable_remote_loopback - echo LCID to enable loopback
|
|
* disable_remote_loopback - echo LCID to enable loopback
|
|
|
|
Driver parameters
|
|
=================
|
|
|
|
A module parameter called debug_mask will be exported to allow a user
|
|
to set the log level for debugging.
|
|
|
|
Config options
|
|
==============
|
|
|
|
No configuration options are planned.
|
|
|
|
Dependencies
|
|
============
|
|
|
|
The msm_rmnet_smux and smux_ctl drivers are part of this project and
|
|
are used to interface with the Linux TCP/IP framework and user space.
|
|
|
|
The physical transport is the HS UART driver which will be extended to
|
|
add a kernel API (the current interface is a TTY interface).
|
|
|
|
Initialization of dependency drivers is handled using the platform
|
|
device framework. When SMUX is loaded as a line discipline of the TTY
|
|
Framework, it will register separate device drivers with the following
|
|
device names:
|
|
* SMUX_CTL
|
|
* SMUX_RMNET
|
|
* SMUX_DUN_DATA_HSUART
|
|
* SMUX_RMNET_DATA_HSUART
|
|
* SMUX_RMNET_CTL_HSUART
|
|
* SMUX_DIAG
|
|
|
|
The drivers are removed when SMUX is unloaded from the line discipline.
|
|
|
|
|
|
User space utilities
|
|
====================
|
|
|
|
No userspace utilities are planned aside from testing and example
|
|
applications.
|
|
|
|
Known issues
|
|
============
|
|
|
|
None.
|
|
|
|
To do
|
|
=====
|
|
Once completed, benchmark to determine if FIFO packet scheduling is
|
|
sufficient or if a different scheduling algorithm such as deficit
|
|
round-robin or deficit FIFO scheduling is needed to fairly handle
|
|
variable-sized packets.
|