RecordReflectionToJson < P1076

P1076 Web>2016_MeetingMarch3>RecordReflectionToJson (2016-03-09, PatrickLehmann) (raw view)EditAttach
---+ RecordIntrospection - Use Case "ToJson"

This use case demonstrates the usage of the proposed introspection capability<br />to convert a complex data structure (nested records and arrays) to a user defined<br />string. The string obeys to the data format rules of JSON (JavaScript Object Notation)

*Sources:*
   * <a href="http://tools.ietf.org/html/rfc4627" target="_blank">RFC 4627</a> - The application/json Media Type for JavaScript Object Notation (JSON)
   * <a href="http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf" target="_blank">ECMA-262</a> - ECMAScript 2015 Language Specification
   * <a href="http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf" target="_blank">ECMA-404</a> - The JSON Data interchange Format
---++ JSON Overview

Here is a simple JSON example: 
<verbatim>[
  {
    "precision": "zip",
    "Latitude":  37.7668,
    "Longitude": -122.3959,
    "Address":   "",
    "City":      "SAN FRANCISCO",
    "State":     "CA",
    "Zip":       "94107",
    "Country":   "US"
  },{
    "precision": "zip",
    "Latitude":  37.371991,
    "Longitude": -122.026020,
    "Address":   "",
    "City":      "SUNNYVALE",
    "State":     "CA",
    "Zip":       "94085",
    "Country":   "US"
   }
]</verbatim>

JSON supports the following data types and literals:
   * boolean values:
      * true and false
   * empty value:
      * null
   * string literals enclosed in double quotes
      * e.g. "my text"
   * integer consecutive decimal digits with an optional minus sign as prefix
      * 32456
   * floating point numbers in common float formatting &lt;sign&gt;&lt;integer part&gt;"."&lt;fractional part&gt;"e"&lt;exp sign&gt;&lt;exponent&gt;
      * e.g. -1.3242e-5
   * list enclosed in brackets and seperated by comas
      * "[" elem1 "," elem2 "," ... "]"
   * associative array (dictionary, hash table) key-value-pais enclosed in braces and seperated by comas
      * "{" KeyValuePair1 "," KeyValuePair2 "," ... "}"
   * key-value-pairs (allowed only in dictionaries) are string keys seperated by a colon from a value
      * string ":" value
Element's data types in lists and dictionaries can be mixed.
---++ The Use Case

I'll use an example from the non-public part of the PoC-Library, so it's a real-life example. Our<br />Serial-ATA controller follows the layered architecture defined by the standard. Each layer has four<br />FIFO based streaming ports (TX in/out and RX in/out) and instantiates several data processing modules<br />in the data flow and one FSM to control and monitor the layer and/or implement the protocol state<br />machine defined in the standard. An upper layer controls and monitors a lower layer using a so called<br /><i>Command-Status-Error</i> interface (CSE). The CSE interface uses 3 enumerated type.
<verbatim>type T_Command is (
  CMD_NONE,
  CMD_WRITE_DMA,
  CMD_READ_DMA
  -- ...
);
type T_Status is (
  STATUS_RESETING,
  STATUS_IDLE,
  STATUS_WRITING,
  STATUS_WRITE_COMPLETE,
  -- ...
  STATUS_ERROR
);
type T_Error is (
  ERROR_NONE,
  ERROR_PROTOCOL,
  ERROR_FIFO_OVERFLOW,
  ERROR_CRC
  -- ...
);</verbatim>

If a Status signal is set to STATUS_ERROR, then the Error signal is valid.

Let's look into the 4 main layers:
   * =StreamingLayer= -&gt; generated ATA commands
   * =TransportLayer= -&gt; pack ATA register for a transfers
   * =LinkLayer= -&gt; frame based data transfer incl. flow control
   * =PhysicalLayer= -&gt; serialization, line encoding, ...
The CSE signals of all layers are made available through a DebugPort to the testbench. So a testbench can<br />monitor all Status or Error signals of every layer and all exchanged commands between the layers. In addition<br />the FIFO interfaces (to the upper layer) are added too, for monitoring in a on-chip logic analyzer. The FIFO<br />interface to the lower layer is not monitored, because it's available through the lower layer.

So let's define records to combine all signals:
<verbatim>type T_FIFO_In is record
  Put   : std_logic;
  Data  : std_logic_vector(31 downto 0);
  Full  : std_logic;
end record;
type T_FIFO_Out is record
  got   : std_logic;
  Data  : std_logic_vector(31 downto 0);
  Valid : std_logic;
end record;
type T_StreamLayer is record
  Command : T_Stream_Command;
  Status  : T_Stream_Status;
  Error   : T_Stream_Error;
  TX      : T_FIFO_In;
  RX      : T_FIFO_Out;
end record;
type T_TransLayer is record
  Command : T_Trans_Command;
  Status  : T_Trans_Status;
  Error   : T_Trans_Error;
  TX      : T_FIFO_In;
  RX      : T_FIFO_Out;
end record;
type T_LinkLayer is record
  Command : T_Link_Command;
  Status  : T_Link_Status;
  Error   : T_Link_Error;
  TX      : T_FIFO_In;
  RX      : T_FIFO_Out;
end record;
type T_PhyLayer is record
  Command : T_Phy_Command;
  Status  : T_Phy_Status;
  Error   : T_Phy_Error;
  TX      : T_FIFO_In;
  RX      : T_FIFO_Out;
end record;
type T_DebugPort is record
  StreamingLayer : T_StreamLayer;
  TransportLayer : T_TransLayer;
  LinkLayer      : T_LinkLayer;
  PhysicalLayer  : T_PhyLayer;
end record;</verbatim>
Let's assume a testbench, which wants to report the overall state of all signals in the DebugPort<br />when an error occurred.
<verbatim>ErrorIndicator <= '1' when ((DebugPort.StreamingLayer.Status = STATUS_ERROR) or
                            (DebugPort.TransportLayer.Status = STATUS_ERROR) or
                            (DebugPort.LinkLayer.Status = STATUS_ERROR) or
                            (DebugPort.PhysicalLayer.Status = STATUS_ERROR)) else
                  '0';

process(DebugPort, ErrorIndicator)
  -- under construction
begin
  -- under construction
end process;</verbatim>

-- %USERSIG{PatrickLehmann - 2016-03-09}%

---++ Comments

<br />%COMMENT%
Topic revision: r2 - 2016-03-09 - 23:46:17 - PatrickLehmann
P1076