sysclk-lwla: Enhance dissector to work with LWLA1016
[sigrok-util.git] / debug / sysclk-lwla / sysclk-lwla-dissector.lua
1 -- SysClk LWLA protocol dissector for Wireshark
2 --
3 -- Copyright (c) 2014,2015 Daniel Elstner <daniel.kitta@gmail.com>
4 --
5 -- This program is free software; you can redistribute it and/or modify
6 -- it under the terms of the GNU General Public License as published by
7 -- the Free Software Foundation; either version 3 of the License, or
8 -- (at your option) any later version.
9 --
10 -- This program is distributed in the hope that it will be useful,
11 -- but WITHOUT ANY WARRANTY; without even the implied warranty of
12 -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 -- GNU General Public License for more details.
14 --
15 -- You should have received a copy of the GNU General Public License
16 -- along with this program; if not, see <http://www.gnu.org/licenses/>.
17
18 -- Usage: wireshark -X lua_script:sysclk-lwla-dissector.lua
19 --
20 -- It is not advisable to install this dissector globally, since
21 -- it will try to interpret the communication of any USB device
22 -- using the vendor-specific interface class.
23
24 -- Create custom protocol for the LWLA logic analyzer.
25 p_lwla = Proto("lwla", "LWLA USB Protocol")
26
27 -- LWLA message type.  For simplicity, the numerical value is the same
28 -- as the USB end point number the message is sent to or comes from.
29 local message_types = {
30     [2] = "Control command",
31     [4] = "Firmware transfer",
32     [6] = "Control response"
33 }
34
35 -- Known IDs of LWLA control commands.
36 local control_commands = {
37     [1] = "Read register",
38     [2] = "Write register",
39     [3] = "Read memory",
40     [5] = "Write ???",
41     [6] = "Read memory",
42     [7] = "Capture setup",
43     [8] = "Capture status"
44 }
45
46 -- Create the fields exhibited by the protocol.
47 p_lwla.fields.msgtype  = ProtoField.uint8("lwla.msgtype", "Message Type", base.DEC, message_types)
48 p_lwla.fields.command  = ProtoField.uint16("lwla.cmd", "Command ID", base.DEC, control_commands)
49 p_lwla.fields.memaddr  = ProtoField.uint32("lwla.memaddr", "Memory Address", base.HEX_DEC)
50 p_lwla.fields.memlen   = ProtoField.uint32("lwla.memlen", "Memory Read Length", base.HEX_DEC)
51 p_lwla.fields.regaddr  = ProtoField.uint16("lwla.regaddr", "Register Address", base.HEX)
52 p_lwla.fields.regdata  = ProtoField.uint32("lwla.regdata", "Register Value", base.HEX_DEC)
53 p_lwla.fields.stataddr = ProtoField.uint16("lwla.stataddr", "Status Memory Address", base.HEX)
54 p_lwla.fields.statlen  = ProtoField.uint16("lwla.statlen", "Status Memory Read/Write Length", base.HEX_DEC)
55 p_lwla.fields.statdata = ProtoField.bytes("lwla.statdata", "Status Word")
56 p_lwla.fields.secdata  = ProtoField.uint32("lwla.secdata", "Security Hash", base.HEX_DEC)
57 p_lwla.fields.unknown  = ProtoField.bytes("lwla.unknown", "Unidentified message data")
58
59 -- Referenced USB URB dissector fields.
60 local f_urb_type = Field.new("usb.urb_type")
61 local f_transfer_type = Field.new("usb.transfer_type")
62 local f_endpoint = Field.new("usb.endpoint_number.endpoint")
63
64 -- Insert warning for undecoded leftover data.
65 local function warn_undecoded(tree, range)
66     local item = tree:add(p_lwla.fields.unknown, range)
67     item:add_expert_info(PI_UNDECODED, PI_WARN, "Leftover data")
68 end
69
70 -- Extract a 32-bit mixed endian word.
71 local function read_mixed_endian(range)
72     return range(0,2):le_uint() * 65536 + range(2,2):le_uint()
73 end
74
75 -- Un-shuffle the bytes of a 64-bit stat field.
76 local function read_stat_field(range)
77     return string.char(range(5,1):uint(), range(4,1):uint(), range(7,1):uint(), range(6,1):uint(),
78                        range(1,1):uint(), range(0,1):uint(), range(3,1):uint(), range(2,1):uint())
79 end
80
81 -- Dissect LWLA1034 capture state.
82 local function dissect_capture_state(range, tree)
83     for i = 0, range:len() - 8, 8 do
84         tree:add(p_lwla.fields.statdata, range(i,8), read_stat_field(range(i,8)))
85     end
86 end
87
88 -- Dissect LWLA control command messages.
89 local function dissect_command(range, pinfo, tree)
90     if range:len() < 4 then
91         return 0
92     end
93
94     tree:add_le(p_lwla.fields.command, range(0,2))
95     local command = range(0,2):le_uint()
96
97     if command == 1 then -- read register
98         if range:len() == 4 then
99             tree:add_le(p_lwla.fields.regaddr, range(2,2))
100             pinfo.cols.info = string.format("Cmd %d: read reg 0x%04X",
101                                             command, range(2,2):le_uint())
102             return 4
103         end
104     elseif command == 2 then -- write register
105         if range:len() == 8 then
106             tree:add_le(p_lwla.fields.regaddr, range(2,2))
107             local regval = read_mixed_endian(range(4,4))
108             tree:add(p_lwla.fields.regdata, range(4,4), regval)
109             pinfo.cols.info = string.format("Cmd %d: write reg 0x%04X value 0x%08X",
110                                             command, range(2,2):le_uint(), regval)
111             return 8
112         end
113     elseif command == 5 then -- write security hash?
114         if range:len() == 66 then
115             local infotext = string.format("Cmd %d: write security hash?", command)
116             for i = 2, 62, 4 do
117                 local value = read_mixed_endian(range(i,4))
118                 tree:add(p_lwla.fields.secdata, range(i,4), value)
119                 infotext = string.format("%s %02X", infotext, value)
120             end
121             pinfo.cols.info = infotext
122             return 66
123         end
124     elseif command == 3 or command == 6 then -- read memory at address
125         if range:len() == 10 then
126             local memaddr = read_mixed_endian(range(2,4))
127             local memlen  = read_mixed_endian(range(6,4))
128             tree:add(p_lwla.fields.memaddr, range(2,4), memaddr)
129             tree:add(p_lwla.fields.memlen,  range(6,4), memlen)
130             pinfo.cols.info = string.format("Cmd %d: read mem 0x%06X length %d",
131                                             command, memaddr, memlen)
132             return 10
133         end
134     elseif command == 7 then -- capture setup (LWLA1034)
135         if range:len() >= 6 then
136             tree:add_le(p_lwla.fields.stataddr, range(2,2))
137             tree:add_le(p_lwla.fields.statlen, range(4,2))
138             local len = 8 * range(4,2):le_uint()
139             if range:len() ~= len + 6 then
140                 warn_undecoded(tree, range(6))
141                 return 6
142             end
143             dissect_capture_state(range(6,len), tree)
144             pinfo.cols.info = string.format("Cmd %d: setup 0x%X length %d",
145                                             command, range(2,2):le_uint(), range(4,2):le_uint())
146             return 6 + len
147         end
148     elseif command == 8 then -- capture status (LWLA1034)
149         if range:len() == 6 then
150             tree:add_le(p_lwla.fields.stataddr, range(2,2))
151             tree:add_le(p_lwla.fields.statlen, range(4,2))
152             pinfo.cols.info = string.format("Cmd %d: state 0x%X length %d",
153                                             command, range(2,2):le_uint(), range(4,2):le_uint())
154             return 6
155         end
156     end
157     warn_undecoded(tree, range(2))
158     return 2
159 end
160
161 -- Dissect LWLA control response messages.
162 local function dissect_response(range, pinfo, tree)
163     -- The heuristics below are ugly and prone to fail, but they do the job
164     -- for the purposes this dissector was written.
165     if range:len() == 40 or range:len() == 80 then -- heuristic: response to command 8
166         dissect_capture_state(range, tree)
167         pinfo.cols.info = string.format("Ret 8: state length %d", range:len() / 8)
168         return range:len()
169     elseif range:len() == 4 then -- heuristic: response to command 1
170         local value = read_mixed_endian(range(0,4))
171         tree:add(p_lwla.fields.regdata, range(0,4), value)
172         pinfo.cols.info = string.format("Ret 1: reg value 0x%08X", value)
173         return 4
174     elseif range:len() == 1000 or range:len() == 552 then -- heuristic: response to command 3
175         pinfo.cols.info = string.format("Ret 3: mem data length %d", range:len() / 4)
176         return 0
177     elseif range:len() >= 18 and range:len() % 18 == 0 then -- heuristic: response to command 6
178         pinfo.cols.info = string.format("Ret 6: mem data length %d", range:len() * 2 / 9)
179         return 0
180     else
181         return 0
182     end
183 end
184
185 -- Main LWLA dissector function.
186 function p_lwla.dissector(tvb, pinfo, tree)
187     local transfer_type = tonumber(tostring(f_transfer_type()))
188
189     -- Bulk transfers only.
190     if transfer_type == 3 then
191         local urb_type = tonumber(tostring(f_urb_type()))
192         local endpoint = tonumber(tostring(f_endpoint()))
193
194         -- Payload-carrying packets only.
195         if (urb_type == 83 and (endpoint == 2 or endpoint == 4))
196             or (urb_type == 67 and endpoint == 6)
197         then
198             pinfo.cols.protocol = p_lwla.name
199
200             local subtree = tree:add(p_lwla, tvb(), "LWLA")
201             subtree:add(p_lwla.fields.msgtype, endpoint):set_generated()
202
203             -- Dispatch to message-specific dissection handler.
204             if endpoint == 2 then
205                 return dissect_command(tvb, pinfo, subtree)
206             elseif endpoint == 4 then
207                 pinfo.cols.info = "FPGA bitstream"
208                 return 0
209             elseif endpoint == 6 then
210                 return dissect_response(tvb, pinfo, subtree)
211             end
212         end
213     end
214     return 0
215 end
216
217 -- Register LWLA protocol dissector during initialization.
218 function p_lwla.init()
219 --    local usb_product_dissectors = DissectorTable.get("usb.product")
220
221     -- Dissection by vendor+product ID requires that Wireshark can get the
222     -- the device descriptor.  Making a USB device available inside VirtualBox
223     -- will make it inaccessible from Linux, so Wireshark cannot fetch the
224     -- descriptor by itself.  However, it is sufficient if the VirtualBox
225     -- guest requests the descriptor once while Wireshark is capturing.
226 --    usb_product_dissectors:add(0x29616688, p_lwla) -- SysClk LWLA1016
227 --    usb_product_dissectors:add(0x29616689, p_lwla) -- SysClk LWLA1034
228
229     -- Addendum: Protocol registration based on product ID does not always
230     -- work as desired.  Register the protocol on the interface class instead.
231     -- The downside is that it would be a bad idea to put this into the global
232     -- configuration, so one has to make do with -X lua_script: for now.
233     local usb_bulk_dissectors = DissectorTable.get("usb.bulk")
234
235     -- For some reason the "unknown" class ID is sometimes 0xFF and sometimes
236     -- 0xFFFF.  Register both to make it work all the time.
237     usb_bulk_dissectors:add(0xFF, p_lwla)
238     usb_bulk_dissectors:add(0xFFFF, p_lwla)
239 end