KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cfg_msg.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  *
4  * Copyright 2013 KM3NeT Collaboration
5  *
6  * All Rights Reserved.
7  *
8  * cfg_msg.h
9  *
10  * Created on: 8 jul. 2013
11  * Author: Vincent van Beveren
12  */
13 
14 #ifndef CFG_REMOTE_H_
15 #define CFG_REMOTE_H_
16 
17 /**
18  * @file
19  *
20  * @ingroup cfg
21  *
22  * Defines all remote commands.
23  *
24  * A command belongs to a group. Each group has a unique identifier. To add a command first find
25  * the correct group, and then add your command ID by defining a new type identifier:
26  *
27  * #define MSG_{group_name}_{cmd_name} MSG_TYPE({group_id}, {#id})
28  *
29  * For example, the reset command would be in the system group, with ID is defined as follows:
30  * @code
31  * #define MSG_SYS_REBOOT MSG_TYPE(GROUP_SYS, 0x2)
32  * @endcode
33  *
34  * Then a link must be made to the actual command. This can be done with the
35  * MSG_CMD({type}, {function suffix}) macro, which should be inside the MSG_<group>_COMMANDS list:
36  *
37  * @code
38  * #define MSG_SYS_COMMANDS \
39  * MSG_CMD(MSG_SYS_PING, Ping) \
40  * MSG_CMD(MSG_SYS_REBOOT, Reboot)
41  * @endcode
42  *
43  * Now the message module (@ref msg.h) will generate a function prototype:
44  * @code
45  * bool _msgReboot(MsgId * msgId, DataBuffer * cmd);
46  * @endcode
47  *
48  * You must then fill in the body of this function. Please see @ref msg.h for more details.
49  */
50 
51 /// Group bit shift.
52 #define MSG_GROUP_SHIFT 6
53 
54 /// Creates a message type.
55 #define MSG_TYPE(GROUP, ID) ( ( ( GROUP ) << ( MSG_GROUP_SHIFT ) ) | ( ID ) )
56 
57 /**
58  * @name Debug Group
59  *
60  * Defines the debug commands. These commands are only used for debugging and should not be used
61  * during normal operation.
62  * @{
63  */
64 
65 /// debugging commands group identifier
66 #define GROUP_DEBUG 0x01
67 
68 #ifndef KM3SIM
69 /// Read & Write Bus commands
70 #define MSG_DBG_BUS_READ MSG_TYPE(GROUP_DEBUG, 0x01)
71 #define MSG_DBG_BUS_WRITE MSG_TYPE(GROUP_DEBUG, 0x02)
72 #define MSG_DBG_BUS_RMW MSG_TYPE(GROUP_DEBUG, 0x03)
73 
74 
75 
76 /// Read & Write I2C (not implemented yet)
77 #define MSG_DBG_I2C_READ MSG_TYPE(GROUP_DEBUG, 0x04)
78 #define MSG_DBG_I2C_WRITE MSG_TYPE(GROUP_DEBUG, 0x05)
79 
80 #define MSG_DBG_UART_TX MSG_TYPE(GROUP_DEBUG, 0x06)
81 #define MSG_DBG_UART_RX MSG_TYPE(GROUP_DEBUG, 0x07)
82 
83 #define MSG_DBG_FLASH_READ MSG_TYPE(GROUP_DEBUG, 0x08)
84 
85 /*
86  * Read a single RX packet log line,.
87  *
88  * Input:
89  * U16 Position
90  *
91  * Returns:
92  * Position invalid:
93  * Empty reply
94  * Otherwise:
95  * U32 Timestamp (local)
96  * U16 Length
97  * U16 EthType
98  * U16 Processing duration (ms)
99  * U8 DEST MAC Octet 5
100  * U8 DEST MAC Octed 6
101  */
102 #define MSG_DBG_RXPKTLOG_READ MSG_TYPE(GROUP_DEBUG, 0x09)
103 #define MSG_DBG_RXPKTLOG_RESET MSG_TYPE(GROUP_DEBUG, 0x0A)
104 
105 /** Define all messages in a list, including function prototype suffix. */
106 #define MSG_DBG_COMMANDS \
107  MSG_CMD(MSG_DBG_BUS_READ, BusRead) \
108  MSG_CMD(MSG_DBG_BUS_WRITE, BusWrite) \
109  MSG_CMD(MSG_DBG_I2C_READ, I2CRead) \
110  MSG_CMD(MSG_DBG_I2C_WRITE, I2CWrite) \
111  MSG_CMD(MSG_DBG_UART_TX, UartTx) \
112  MSG_CMD(MSG_DBG_UART_RX, UartRx) \
113  MSG_CMD(MSG_DBG_FLASH_READ, FlashRead) \
114  MSG_CMD(MSG_DBG_RXPKTLOG_READ, RxPktLogRead) \
115  MSG_CMD(MSG_DBG_RXPKTLOG_RESET, RxPktLogReset) \
116 
117 #else
118 #define MSG_DBG_COMMANDS
119 #endif
120 /** @} */
121 
122 /**
123  * @name System Group
124  *
125  * Defines the system group commands. System group commands are not specific to the functionality
126  * of the software, but general. For example, version information is generic, system load
127  * values etc.
128  * @{
129  */
130 
131 
132 #define GROUP_SYS 0x02 /// system commands group identifier
133 
134 /// Ping command
135 #define MSG_SYS_PING MSG_TYPE(GROUP_SYS, 0x01)
136 
137 /// Date and Revision Information
138 #define MSG_SYS_DATEREV MSG_TYPE(GROUP_SYS, 0x02)
139 
140 /// Sets the sender as the event target, after this all events, will be send to this target.
141 #define MSG_SYS_EVT_TARGET MSG_TYPE(GROUP_SYS, 0x03)
142 
143 /// Resets the board
144 #define MSG_SYS_RESET MSG_TYPE(GROUP_SYS, 0x04)
145 
146 /// Command required for starting an update
147 #define MSG_SYS_UPDATE_START MSG_TYPE(GROUP_SYS, 0x05)
148 
149 /// Event emitted to update a part of a firmware image (broadcast)
150 #define EVT_SYS_UPDATE MSG_TYPE(GROUP_SYS, 0x06)
151 
152 /// Command to update a part of a firmware image(unicast)
153 #define MSG_SYS_UPDATE MSG_TYPE(GROUP_SYS, 0x06)
154 
155 
156 /// Command to end the update procedure
157 #define MSG_SYS_UPDATE_END MSG_TYPE(GROUP_SYS, 0x07)
158 
159 
160 /// Command to verify image data on the flash
161 #define MSG_SYS_VERIFY MSG_TYPE(GROUP_SYS, 0x08)
162 
163 /// Command to issue boot of specific image
164 #define MSG_SYS_BOOT MSG_TYPE(GROUP_SYS, 0x09)
165 
166 /// Command to stop the golden image for proceeding and booting the main image.
167 /// Will not do anything for the normal runtime image.
168 #define MSG_SYS_GOLDEN_STOP MSG_TYPE(GROUP_SYS, 0x0A)
169 
170 /// Unlocks the golden image for writing
171 #define MSG_SYS_GOLDEN_UNLOCK MSG_TYPE(GROUP_SYS, 0x0B)
172 
173 /// Get the last live log lines
174 #define MSG_SYS_LOG_GET MSG_TYPE(GROUP_SYS, 0x0C)
175 
176 /**
177  * Get the last persistent log lines. Oldest first.
178  *
179  * Call first with an 32 bit integer, for the number of log-lines.
180  *
181  * The returned message contains a batch of strings.
182  *
183  * Call the function again but w/o the 32 bit integer to continue to read the next log lines.
184  *
185  * Call as long as the last string as not empty. Once you read an empty line the output is at
186  * an end.
187  *
188  */
189 #define MSG_SYS_P_LOG_GET MSG_TYPE(GROUP_SYS, 0x0D)
190 
191 /**
192  * Returns information on the images in the current CLB
193  *
194  * Off Len Type Description
195  * 0 1 U8 Number of positions, N, let n = { 0 .. N-1 }
196  * 9n + 1 4 U32 Firmware version / date
197  * 9n + 5 4 U32 Software version / date
198  * 9n + 9 1 I8 The image type, where
199  * -1: No image
200  * 0: Uknown image (there is an image, but there is no meta-data)
201  * 1: Golden
202  * 2: Runtime
203  * 3: Base
204  * 4: Calibration
205  */
206 #define MSG_SYS_IMG_GET MSG_TYPE(GROUP_SYS, 0x0E)
207 
208 /// Command to issue boot of specific image
209 #define MSG_SYS_COREDUMP_CLR MSG_TYPE(GROUP_SYS, 0x0F)
210 
211 
212 /**
213  * Initialize/uninitialize console tunnel.
214  *
215  * When provided with a 32-bit integer + 16 bit port number tunneling is configured.
216  * If the both numbers are zero, the sender IP and PORT are used.
217  *
218  * When provided with no arguments tunneling is uninitialized. It is custom to do this before
219  * disconnecting. Otherwise stale packets will be send.
220  */
221 #define MSG_SYS_CONTUN_INIT MSG_TYPE(GROUP_SYS, 0x10)
222 
223 /**
224  * Send one or more characters to a console. Two strings must be provided. First string is for the
225  * PTP core, second is for the LM32. Strings may be empty.
226  */
227 #define MSG_SYS_CONTUN_SEND MSG_TYPE(GROUP_SYS, 0x11)
228 
229 /**
230  * Event when character data is available on any of the consoles. Also includes two strings. First
231  * string is of the PTP core, second is of the LM32.
232  */
233 #define EVT_SYS_CONTUN_RECV MSG_TYPE(GROUP_SYS, 0x12)
234 
235 /**
236  * Gets/Sets the runtime configuration.
237  *
238  * When queried with no payload, the runtime configuration is returned.
239  *
240  * The runtime configuration can also be set if put into the payload of
241  * the request.
242  *
243  * Runtime configuration set
244  * -------------------------
245  * Off Len Type Description
246  * 0 1 U8 Version (must be 1 when setting)
247  * 1 1 U8 Runtime image number to start after golden (1..3)
248  */
249 #define MSG_SYS_RT_CONFIG MSG_TYPE(GROUP_SYS, 0x18)
250 
251 
252 
253 
254 /** Define all messages in a list, including function prototype suffix. */
255 #define MSG_SYS_COMMANDS \
256  MSG_CMD(MSG_SYS_PING, Ping) \
257  MSG_CMD(MSG_SYS_DATEREV, DateRev) \
258  MSG_CMD(MSG_SYS_EVT_TARGET, EvtTarget) \
259  MSG_CMD(MSG_SYS_RESET, Reset) \
260  MSG_CMD(MSG_SYS_UPDATE_START, SysUpdateStart) \
261  MSG_CMD(MSG_SYS_UPDATE, SysUpdateRecv) \
262  MSG_CMD(MSG_SYS_UPDATE_END, SysUpdateEnd) \
263  MSG_CMD(MSG_SYS_VERIFY, SysUpdateVerify)\
264  MSG_CMD(MSG_SYS_BOOT, Boot) \
265  MSG_CMD(MSG_SYS_GOLDEN_STOP, GoldenStop) \
266  MSG_CMD(MSG_SYS_GOLDEN_UNLOCK, GoldenUnlock) \
267  MSG_CMD(MSG_SYS_LOG_GET, LogGet) \
268  MSG_CMD(MSG_SYS_P_LOG_GET, PLogGet) \
269  MSG_CMD(MSG_SYS_IMG_GET, ImgGet) \
270  MSG_CMD(MSG_SYS_COREDUMP_CLR, CoreDumpClr) \
271  MSG_CMD(MSG_SYS_CONTUN_INIT, ConTunInit) \
272  MSG_CMD(MSG_SYS_CONTUN_SEND, ConTunSend) \
273  MSG_CMD(MSG_SYS_RT_CONFIG, RtConfig)
274 
275 
276 /** Define all events which can be received. */
277 #define MSG_SYS_EVENTS \
278  MSG_EVT(EVT_SYS_UPDATE, SysUpdateRecv) \
279  MSG_EVT(EVT_SYS_CONTUN_RECV, ConTunRecv)
280 
281 
282 
283 /** @} */
284 
285 /**
286  * @name CLB Group
287  *
288  * Defines commands in the CLB group. The CLB group contains commands which are not tied to a
289  * specific peripheral. For example, state change commands, configuration commands, or generic
290  * status requests should be in this group.
291  * @{
292  */
293 
294 #define GROUP_CLB 0x03 /// CLB group id
295 
296 // Gets the state
297 #define MSG_CLB_GET_STATE MSG_TYPE(GROUP_CLB, 0x01)
298 
299 // Directs the device to go to a state
300 #define MSG_CLB_EVENT MSG_TYPE(GROUP_CLB, 0x02)
301 
302 // Event emitted when the state is changed
303 #define EVT_CLB_STATE MSG_TYPE(GROUP_CLB, 0x03)
304 
305 // Event emitted periodically containing system information
306 #define EVT_CLB_UPDATE MSG_TYPE(GROUP_CLB, 0x04)
307 
308 // Activate configuration (not used)
309 #define MSG_CLB_ACTIVATE_CFG MSG_TYPE(GROUP_CLB, 0x05)
310 
311 // Store a configuration (not used)
312 #define MSG_CLB_STORE_CFG MSG_TYPE(GROUP_CLB, 0x06)
313 
314 // Returns one or more process variables
315 #define MSG_CLB_GET_VARS MSG_TYPE(GROUP_CLB, 0x07)
316 
317 // Sets one or more process variables
318 #define MSG_CLB_SET_VARS MSG_TYPE(GROUP_CLB, 0x08)
319 
320 // Subscribes to one or more variables
321 #define MSG_CLB_SUB_VARS MSG_TYPE(GROUP_CLB, 0x09)
322 
323 // Subscribes to one or more variables
324 #define MSG_CLB_UNSUB_VARS MSG_TYPE(GROUP_CLB, 0x10)
325 
326 // Event emitted with the subscribed variables, will replace MSG_CLB_UPDATE later on.
327 #define EVT_CLB_UPDATE_VARS MSG_TYPE(GROUP_CLB, 0x11)
328 
329 // Extended state information for all subsystems
330 #define MSG_CLB_EXT_UPDATE MSG_TYPE(GROUP_CLB, 0x12)
331 
332 /**
333  * Clear the error state.
334  *
335  * Command pay-load:
336  * SUBID u8 Subsystem ID
337  *
338  * Reply:
339  * -
340  */
341 #define MSG_CLB_CLR_ERR_STATE MSG_TYPE(GROUP_CLB, 0x13)
342 
343 /**
344  * Subscribes to one or more variables with a specific rate
345  *
346  * Command pay-load:
347  * RATE u8 Rate:
348  * 0 - each frame
349  * 1 - each second
350  * 2 - every 10 seconds
351  * 3 - every 60 seconds.
352  * COUNT u16 No. of vars
353  * VARIDS i32[COUNT] Variable ID of each variable.
354  */
355 #define MSG_CLB_SUB_VARSRATE MSG_TYPE(GROUP_CLB, 0x14)
356 
357 
358 /** Define all messages in a list, including function prototype suffix. */
359 #define MSG_CLB_COMMANDS \
360  MSG_CMD(MSG_CLB_GET_STATE, ClbGetState) \
361  MSG_CMD(MSG_CLB_EVENT, ClbEvent) \
362  MSG_CMD(MSG_CLB_GET_VARS, ClbGetVars) \
363  MSG_CMD(MSG_CLB_SET_VARS, ClbSetVars) \
364  MSG_CMD(MSG_CLB_SUB_VARS, ClbSubVars) \
365  MSG_CMD(MSG_CLB_UNSUB_VARS, ClbUnSubVars) \
366  MSG_CMD(MSG_CLB_EXT_UPDATE, ClbExtUpdate) \
367  MSG_CMD(MSG_CLB_CLR_ERR_STATE, ClbClrErrState) \
368  MSG_CMD(MSG_CLB_SUB_VARSRATE, ClbSubVarsRate)
369 
370 /** @} */
371 
372 /**
373  * @name Network Group
374  *
375  * Defines all commands for network configuration.
376  *
377  * @{
378  */
379 
380 #define GROUP_NET 0x04 /// IP Networ group id
381 
382 // Set the IP of the MUX destination
383 #define MSG_NET_MUX_DEST MSG_TYPE(GROUP_NET, 0x01)
384 /**
385  * Gets wavelength tuning info
386  *
387  * REQUEST:
388  *
389  * Emtpy
390  *
391  *
392  * RESPONSE:
393  *
394  * Off Len Type Description
395  * -------- ---- ------ -------------------------------------------------------
396  * 0 1 U8 WL Tuning vendor procedure where
397  * 0 - Not supported
398  * 1 - EOPTOLINK procedure (Tuning word must be -80 to 80)
399  * 2 - OESolutions procedure (Tuning word must be 0-65536)
400  * 3..255 - Reserved
401  * 1 1 U8 Status bit field
402  * Bits 2..0: State (enumeration)
403  * 0 - Idle
404  * 1 - Busy
405  * 2 - Waiting for ACK
406  * 7 - Reserved
407  * Bit 3 : Last ACK failed, laser reset
408  * 2 2 U16 Value from the Optional Laser Wavelength (SFP+ Addr A2, 106-107)
409  * or 0x0000 if not implemented.
410  * 4 4 I32 Current Tuning word value (must in in range of procedure)
411  */
412 #define MSG_NET_WL_TUNE_INFO MSG_TYPE(GROUP_NET, 0x02)
413 
414 /**
415  * Set wavelength tuning word
416  *
417  * REQUEST:
418  *
419  * Off Len Type Description
420  * -------- ---- ------ -------------------------------------------------------
421  * 0 4 I32 Tuning word to set, must be in supported range.
422  * See byte 0 of WL_TUNE_INFO response
423  *
424  * RESPONE:
425  *
426  * Ack or Error. After ACK the WL will be tuned
427  */
428 #define MSG_NET_WL_TUNE_SET MSG_TYPE(GROUP_NET, 0x03)
429 
430 /**
431  * Send ACK, to confirm tuning. Must be done within 15 seconds.
432  *
433  * REQUEST:
434  *
435  * Empty
436  *
437  * RESPONE:
438  *
439  * Ack or Error.
440  */
441 #define MSG_NET_WL_TUNE_ACK MSG_TYPE(GROUP_NET, 0x04)
442 
443 /** Define all messages in a list, including function prototype suffix. */
444 #define MSG_NET_COMMANDS \
445  MSG_CMD(MSG_NET_MUX_DEST, NetMuxDest) \
446  MSG_CMD(MSG_NET_WL_TUNE_INFO, NetWlTuneInfo) \
447  MSG_CMD(MSG_NET_WL_TUNE_SET, NetWlTuneSet) \
448  MSG_CMD(MSG_NET_WL_TUNE_ACK, NetWlTuneAck) \
449 
450 
451 /** @} */
452 
453 
454 
455 /**
456  * @name OPT Group
457  *
458  *
459  * All commands for controlling the optical detector of the CLB, i.e. PMTs, TDCs, etc...
460  *
461  * @todo
462  *
463  * @{
464  */
465 
466 #define GROUP_OPT 0x05 /// OPT group id
467 
468 
469 /** Define all messages in a list, including function prototype suffix. */
470 #define MSG_OPT_COMMANDS
471 /** @} */
472 
473 
474 /**
475  * @name Acoustics Group
476  *
477  * Description not yet written
478  *
479  * @todo
480  *
481  * @{
482  */
483 
484 #define GROUP_ACS 0x06 /// Acoustics group id
485 
486 
487 
488 /** Define all messages in a list, including function prototype suffix. */
489 #define MSG_ACS_COMMANDS
490 
491 /** @} */
492 
493 /**
494  * @name Instrumetnation group
495  *
496  * This group contains peripherals that do not require a lot of commands.
497  *
498  * @todo
499  *
500  * @{
501  */
502 
503 #define GROUP_INS 0x08 /// Other peripherals group id
504 
505 
506 #define MSG_INS_AHRS_SET_REG MSG_TYPE(GROUP_INS, 0x01)
507 #define MSG_INS_AHRS_GET_REG MSG_TYPE(GROUP_INS, 0x02)
508 #define MSG_INS_AHRS_GET_REG_EX MSG_TYPE(GROUP_INS, 0x03)
509 
510 
511 /** Define all messages in a list, including function prototype suffix. */
512 #define MSG_INS_COMMANDS \
513  MSG_CMD(MSG_INS_AHRS_SET_REG, InsAHRSSetReg) \
514  MSG_CMD(MSG_INS_AHRS_GET_REG, InsAHRSGetReg) \
515  MSG_CMD(MSG_INS_AHRS_GET_REG_EX,InsAHRSGetRegEx)
516 
517 
518 
519 #define GROUP_BSE 0x07 /// Base group
520 
521 
522 #define MSG_BSE_CONFIGURE MSG_TYPE(GROUP_BSE, 0x01)
523 #define MSG_BSE_RESET MSG_TYPE(GROUP_BSE, 0x02)
524 
525 #define MSG_BSE_EDFA_DBG_CMD MSG_TYPE(GROUP_BSE, 0x11) // Debugging
526 #define MSG_BSE_EDFA_DBG_CMDRPLY MSG_TYPE(GROUP_BSE, 0x12)
527 
528 /**
529  * BSP Debug Command/Reply
530  *
531  * Command:
532  * u8 cmdCode BPS command code
533  * u8 rplCode Expected BPS reply code
534  * u8 rplNData Expected number of returned bytes
535  * u8 cmdNData Number of command bytes
536  * u8[cmdNData] cmdData Command data
537  *
538  * Reply:
539  * u8 rplNData Number of returned bytes
540  * u8[rplNData] rplData Reply data
541  * u8 cmdCode* Command which caused the reply
542  * u8 rplCode* Reply code
543  *
544  * * Added as of 1 dec 2015, VvB
545  */
546 #define MSG_BSE_BPS_DBG_CMDRPLY MSG_TYPE(GROUP_BSE, 0x13)
547 
548 
549 /** Define all messages in a list, including function prototype suffix. */
550 #define MSG_BSE_COMMANDS \
551  MSG_CMD(MSG_BSE_CONFIGURE, BseConfigure) \
552  MSG_CMD(MSG_BSE_RESET, BseReset) \
553  MSG_CMD(MSG_BSE_EDFA_DBG_CMD, BseEdfaDbgCmd) \
554  MSG_CMD(MSG_BSE_EDFA_DBG_CMDRPLY, BseEdfaDbgCmdRply) \
555  MSG_CMD(MSG_BSE_BPS_DBG_CMDRPLY, BseBpsDbgCmdRply)
556 
557 
558 /** @} */
559 
560 /// List containing all events
561 #define MSG_EVENTS \
562  MSG_SYS_EVENTS
563 
564 /// List containing all commands
565 #define MSG_COMMANDS \
566  MSG_DBG_COMMANDS \
567  MSG_SYS_COMMANDS \
568  MSG_CLB_COMMANDS \
569  MSG_NET_COMMANDS \
570  MSG_OPT_COMMANDS \
571  MSG_ACS_COMMANDS \
572  MSG_INS_COMMANDS \
573  MSG_BSE_COMMANDS
574 
575 
576 #endif /* CFG_REMOTE_H_ */
577 
578 
579