/*
 * This header defines and describes (through comments) the local UNIX domain
 * socket interface implemented between rvinterf and its clients like fc-tmsh.
 *
 * The UNIX domain sockets used for this ad hoc interface are of the
 * SOCK_STREAM kind, but the true nature of the communication is message-based.
 * We use the same trick that is used for DNS over TCP: every message in each
 * direction is preceded by a 2-byte length.  This length is sent MSB first
 * just like in DNS over TCP.  The limit on the size of these messages
 * (for sizing buffers etc) is:
 */

#define	LOCALSOCK_MAX_MSG	1024

/*
 * Each message in the client->rvinterf direction (can be seen as command)
 * begins (after the length) with an opcode byte as follows:
 */

#define	CLI2RVI_WANT_RVTRACE		0x00
#define	CLI2RVI_WANT_MUXPROTO		0x01
#define	CLI2RVI_PKT_TO_TARGET		0x02
#define	CLI2RVI_RAWBYTES_TO_TARGET	0x03
#define	CLI2RVI_RESET_PACKET_RX		0x04
#define	CLI2RVI_DROP_MUXPROTO		0x05

/*
 * The first two commands (CLI2RVI_WANT_RVTRACE and CLI2RVI_WANT_MUXPROTO)
 * are the means by which client programs inform rvinterf that they are
 * interested in receiving copies of certain packets coming from the target.
 *
 * The CLI2RVI_WANT_RVTRACE opcode needs to be followed by a USEID mask value
 * and a USEID match value, both in the network byte order, i.e., MSB first,
 * for a total message length of 9 bytes.  For every RV trace message received
 * from the target, rvinterf will iterate through all active clients to see who
 * is interested: if the received USEID ANDed with the mask equals the match
 * value, the message will be forwarded to that client.
 *
 * The CLI2RVI_WANT_MUXPROTO opcode needs to be followed by one byte
 * identifying the RVTMUX protocol of interest, i.e., the first byte of the
 * packets exchanged between the host and the target, e.g., 0x12 for L1 traces
 * as defined in pktmux.h, for a total message length of 2 bytes.
 *
 * The CLI2RVI_RESET_PACKET_RX opcode resets the "interests" previously set
 * with CLI2RVI_WANT_RVTRACE and/or CLI2RVI_WANT_MUXPROTO.  It is a "blanket"
 * reset; the command message consists of just the opcode.  The
 * CLI2RVI_DROP_MUXPROTO command is more specific and undoes the effect of a
 * previous CLI2RVI_WANT_MUXPROTO; it needs to be followed by one byte
 * identifying the RVTMUX protocol in question, just like CLI2RVI_WANT_MUXPROTO.
 *
 * The last two commands (CLI2RVI_PKT_TO_TARGET and CLI2RVI_RAWBYTES_TO_TARGET)
 * cause data payload to be sent to the target serial port.  Payload following
 * CLI2RVI_PKT_TO_TARGET (must not exceed MAX_PKT_TO_TARGET) is sent with the
 * proper packet encapsulation per TI; bytes following
 * CLI2RVI_RAWBYTES_TO_TARGET are sent raw.
 */

/*
 * Each message in the rvinterf->client direction begins (after the length)
 * with a message type byte as follows:
 */

#define	RVI2CLI_PKT_FROM_TARGET		0x00
#define	RVI2CLI_LOCAL_CMD_RESP		0x01

/*
 * Messages beginning with RVI2CLI_PKT_FROM_TARGET are packets received
 * from the target GSM device; the byte following this type code is the
 * first byte of the packet from the target, e.g., 0x11 for RV traces or
 * 0x12 for L1 traces.  Rvinterf will only start sending these messages
 * to a client after that client has expressed interest in receiving
 * target->host packets of a particular type.
 *
 * Messages beginning with RVI2CLI_LOCAL_CMD_RESP are generated locally
 * by rvinterf itself as responses to commands, currently as responses to
 * CLI2RVI_WANT_{RVTRACE,MUXPROTO}.  The byte following the
 * RVT2CLI_LOCAL_CMD_RESP type code is ASCII '+' or ASCII '-', indicating
 * success or error, respectively.  Any remaining bytes form a message
 * for the user.
 */