#
# Copyright 2007 Free Software Foundation, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#


FIXME Needless to say, this is _very much_ a work in progress



This file specifies the format of ethernet packets used for in-band data
transmission and signaling on the USRP2.

IN packets are sent towards the host.
OUT packets are sent away from the host.

The layout is 32-bits wide.  All data is transmitted in BIG-endian
format across the ethernet.


   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Chan   |                     mbz                       |I|S|E|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Timestamp                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   +                                                               +
   |                            Payload                            |
   .                                                               .
   .                                                               .
   .                                                               .
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+



  mbz   Must be Zero: these bits must be zero in both IN and OUT packets.

  I	Send Immediately. Set on Tx data that should be transmitted now.
	FIXME: change definition to honor 0xffffffff timestamp.

  S     Start of Burst Flag:  Set in an OUT packet if the data is the
        first segment of what is logically a continuous burst of data.
        Must be zero in IN packets.

  E     End of Burst Flag:  Set in an OUT packet if the data is the
        last segment of what is logically a continuous burst of data.
        Must be zero in IN packets.  Underruns are not reported
        when the FPGA runs out of samples between bursts.


  Chan  5-bit logical channel number.  Channel number 0x1f is reserved
        for control information.  See "Control Channel" below.  Other
        channels are "data channels."  Each data channel is logically
        independent of the others.  A data channel payload field
        contains a sequence of homogeneous samples.  The format of the
        samples is determined by the configuration associated with the
        given channel.  It is often the case that the payload field
        contains 32-bit complex samples, each containing 16-bit real
        and imaginary components.

  Timestamp: 32-bit timestamp.

	FIXME: update to reflect that the time is measured at the
	time the samples inserted into or pulled out of the 
	DSP pipeline, not the A/D time.  Using A/D time is problematic
	because of group delay through filtering, etc.

	On IN packets, the timestamp indicates the time at which the
	first sample of the packet was produced by the A/D converter(s)
        for that channel.  On OUT packets, the timestamp specifies the
        time at which the first sample in the packet should go out the
        D/A converter(s) for that channel.  If a packet reaches the
	head of the transmit queue, and the current time is later than
	the timestamp, an error is assumed to have occurred and the
	packet is discarded.  As a special case, the timestamp
	0xffffffff is interpreted as "Now".

	The time base is a free running 32-bit counter that is
	incremented by the A/D sample-clock.

  Payload: Variable length field.  Length is specified by the
        length of the containing ethernet frame.


// FIXME need to revisit this stuff

  O     Overrun Flag: set in an IN packet if an overrun condition was
        detected.  Must be zero in OUT packets.  Overrun occurs when
        the FPGA has data to transmit to the host and there is no
        buffer space available.  This generally indicates a problem on
        the host.  Either it is not keeping up, or it has configured
        the FPGA to transmit data at a higher rate than the transport
        (USB) can support.

  U     Underrun Flag: set in an IN packet if an underrun condition
        was detected.  Must be zero in OUT packets.  Underrun occurs
        when the FPGA runs out of samples, and it's not between
        bursts.  See the "End of Burst flag" below.

  D     Dropped Packet Flag: Set in an IN packet if the FPGA
	discarded an OUT packet because its timestamp had already
	passed.


  RSSI  6-bit Received Strength Signal Indicator:  Must be zero in OUT
        packets.  In IN packets, indicates RSSI as reported by front end.
	FIXME The format and interpretation are to be determined.


  Tag   4-bit tag for matching IN packets with OUT packets.
        [FIXME, write more...]



"Data Channel" payload format:
-------------------------------

If Chan != 0x1f, the packet is a "data packet" and the payload is a
sequence of homogeneous samples.  The format of the samples is
determined by the configuration associated with the given channel.  
It is often the case that the payload field contains 32-bit complex
samples, each containing 16-bit real and imaginary components.


"Control Channel" payload format:
---------------------------------

If Chan == 0x1f, the packet is a "control packet".  The control channel
payload consists of a sequence of 0 or more sub-packets.

Each sub-packet starts on a 32-bit boundary, and consists of an 8-bit
Opcode field, an 8-bit Length field, Length bytes of arguments, and 0,
1, 2 or 3 bytes of padding to align the tail of the sub-packet to
a 32-bit boundary.

Control channel packets shall be processed at the head of the queue,
and shall observe the timestamp semantics described above.


General sub-packet format:
--------------------------

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+
   |     Opcode    |    Length     |        <length bytes> ...    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-//-+-+-+-+-+-+-+-+


Specific sub-packet formats:
----------------------------

  RID: 8-bit Request-ID. Copied from request sub-packet into corresponding
       reply sub-packet.  RID allows the host to match requests and replies.

  Reg Number: 8-bit Register Number.



Identify:

    Opcode:	OP_ID

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       2       |       RID     |      mbz      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Identify Reply:

    Opcode:	OP_ID_REPLY

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |      50       |      RID      |      mbz      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Mac Addr 0   |  Mac Addr 1   |  Mac Addr 2   |  Mac Addr 3   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Mac Addr 4   |  Mac Addr 5   | H/W rev major | H/W rev minor |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Serial Num 0  | Serial Num 1  | Serial Num 2  | Serial Num 3  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Serial Num 4  | Serial Num 5  | Serial Num 6  | Serial Num 7  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   +                                                               +
   |                                                               |
   +                         FPGA MD5SUM                           +
   |                                                               |
   +                                                               +
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   +                                                               +
   |                                                               |
   +                          S/W MD5SUM                           +
   |                                                               |
   +                                                               +
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Write Register:

    Opcode:	OP_WRITE_REG

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       6       |      mbz      |   Reg Number  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        Register Value                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Write Register Masked:

    Opcode:	OP_WRITE_REG_MASKED

    REG[Num] = (REG[Num] & ~Mask) | (Value & Mask)

    That is, only the register bits that correspond to 1's in the
    mask are written with the new value.


   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |      10       |      mbz      |   Reg Number  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Register Value                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Mask Value                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Read Register:

    Opcode:	OP_READ_REG

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       2       |      RID      |   Reg Number  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Read Register Reply:

    Opcode:	OP_READ_REG_REPLY

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       6       |      RID      |   Reg Number  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        Register Value                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


// FIXME these may not be implemented...

I2C Write:

    Opcode:	OP_I2C_WRITE
    I2C Addr:   7-bit I2C address
    Data:	The bytes to write to the I2C bus
    Length:     Length of Data + 2

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |    Length     |      RID      |    I2C Addr   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Data ...			                           .
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


I2C Write Reply:

    Opcode:	OP_I2C_WRITE_REPLY
    Length:     2

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       2       |      RID      |      OK       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


OK is 1 if successful, else 0.


I2C Read:

    Opcode:	OP_I2C_READ
    I2C Addr:	7-bit I2C address
    Nbytes:	Number of bytes to read from I2C bus

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       3       |      RID      |    I2C Addr   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Nbytes    |              unspecified padding              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


I2C Read Reply:

    Opcode:	OP_I2C_READ_REPLY
    I2C Addr:	7-bit I2C address
    Data:	Length - 2 bytes of data read from I2C bus.

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |     Length    |      RID      |      OK       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Data ...			                           .
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

OK is 1 if successful, else 0


SPI Write:

    Opcode:	      OP_SPI_WRITE
    Enables:	      Which SPI enables to assert (mask)
    Format:	      Specifies format of SPI data and Opt Header Bytes
    Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format
    Data:	      The bytes to write to the SPI bus
    Length:	      Length of Data + 6

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |     Length    |      RID      |      mbz      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Enables    |    Format     |        Opt Header Bytes       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Data ...			                           .
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


SPI Write Reply:

    Opcode:	OP_SPI_WRITE_REPLY
    Length:     2

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       2       |      RID      |      OK       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


OK is 1 if successful, else 0.


SPI Read:

    Opcode:	      OP_SPI_READ
    Enables:	      Which SPI enables to assert (mask)
    Format:	      Specifies format of SPI data and Opt Header Bytes
    Opt Header Bytes: 2-byte field containing optional Tx bytes; see Format
    Nbytes:	      Number of bytes to read from SPI bus.

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       7       |      RID      |      mbz      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Enables    |    Format     |        Opt Header Bytes       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Nbytes    |              unspecified padding              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


SPI Read Reply:

    Opcode:   OP_SPI_READ_REPLY
    Data:     Length - 2 bytes of data read from SPI bus.

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |     Length    |    RID    |        mbz        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Data ...			                           .
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Delay:

    Opcode:	OP_DELAY
    Ticks:	16-bit unsigned delay count

    Delay Ticks clock ticks before executing next operation.

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Opcode    |       2       |            Ticks              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+