UDP_Framework - david-macmahon/wiki_convert_test GitHub Wiki
There is currently an effort underway to create a framework to allow the control of all CASPER hardware using a single, well-defined packet structure.
Operation
Each board will run a UDP server and will respond to requests from remote machines. The interface is very simple in the interests of keeping network and CPU overhead low. The idea is that you can implement the server or client in any language you like (Python, Ruby, "C", Fortran etc) as long as the packet formats remain consistent.
Developers
- Arash Parsa (BORPH server, "C" client)
- Jason Manley (BORPH server, Python client)
- Terry Filiba (BORPH server, "C" client)
- John Ford (iBOB server)
- Andrew Siemion (iBOB consultant)
- Henry Chen (toolflow update)
Status
- Dec 2007: Jason begins coding the BORPH server. This codebase has been passed on to Arash for completion.
- Dec 2007: John Ford begins porting to iBOB.
- Jan 2008: Arash reports that BORPH server is complete and that the client is ~90% complete
- Feb 2008: Beta Borph C server and Python Client completed.
- Feb 2008: Jason testing. Correlator monitoring and control port begin.
Bugs
C_Borphserver
- Indexed write
Not yet tested
- Non-indexed read/write
Should open new file descriptors, rather than using already open files. This is a problem with registers representing files of indeterminate size (such as 10GbE config core which should be 79, not 1). Problem is that reading/writing doesn't rewind to start of file. Unless you read the correct number of bytes so that it wraps around, the next read/write is corrupt.
Additionally, this should be corrected in the base package/matlab scripts so that BORPH knows the 10GbE core config length.
- EXEC
Sometimes ignores arguments.
-
- Fixed. JRM. 2008-09-12. Indexing fault.
Python Client
- Indexed write
Not yet implemented
Documentation
This was originally written in LaTeX, so excuse any formatting errors that may crop-up here. I have decided that it would be better to have a copy on the wiki to allow everyone to look at it and discuss adding features.
Supported Commands
Each command that has an expected return value also takes a tag argument, which is included in the return packet and can be used by the user to identify the source. Unless otherwise specified, all strings are null terminated.
- LISTDEV
Lists the devices and software registers on the FPGA device.
- LISTBOF
Lists the bof files available on the server.
- LISTCMD
Lists the commands available for execution on the server. In the case of BORPH, this simply requests a list of files in the "commands" directory. In the case of the IBOB, this prints a list of the custom-executable compiled commands.
- PROGDEV
Allows the user to load bitstreams remotely (program the FPGA). The user specifies the \textit{.bof} file to use, which is located in a designated folder on the server.
- STATUS
Requests a status report from the server. This will indicate whether or not the FPGA is currently programmed, and if so, which process occupies it.
- EXEC
Execute a command remotely. A string is sent and the command is executed verbatim (as if entered on the command line on BORPH). In the case of the IBOB, this string should be one of the custom-commands as listed by LISTCMND. Returns a packet EXECREPORT showing pid of exec'd process. Idea is to have the executed program report additional info itself should it be required.
- READ
Allows data to be read from the device. The user specifies the register name, the start address and the number of bytes to retrieve.
- WRITE
Allows data to be written to the device. The user specifies the target register and the start and stop offsets. This allows limited data to be written into BRAMS.
- INDEXEDREAD
Allows data to be read from the device using an index (results in higher performance and smaller data packets). The index corresponds to the order of returned data from LISTDEV. Index is numbered from zero.
- INDEXEDWRITE
Allows data to be written to the device. Data is specified in raw binary as 8 bit values. No network reordering takes place.The index corresponds to the order of returned data from LISTDEV. Index is numbered from zero.
Returned Packets
- ERR
An error packet indicating that the requested command could not be executed. The included ID tag and message will identify the cause of the error.
- AVAILCMND
Returns a list of the commands on the server available for execution. These are executable files located in the "commands" directory on the server. Issued in response to a LISTCMD command.
- AVAILBOF
Returns a list of the BORPH files (*.bof) located in the executable directory. Issued in response to a LISTBOF command.
- AVAILDEV
Returns a list of the devices on the FPGA. It is issued in response to a LISTDEV command. If no devices are found (for example, if the FPGA is not yet configured), an error message will be issued instead.
- REPORT
Returns device status in the form of a string. Issued in response to a STATUS command request.
- EXECREPORT
Returns PID of executed process. Represents successful execution.
- DATA
Returns the requested data in raw binary form.
UDP Packet Format
The first byte is the identifier and it indicates the packet type. Thereafter, each packet has its own format:
Sent Packets
- PROGDEV
Packet type identifier = 10 (decimal)
Total Length: 1 + len(filename) Bytes
| Name | Size (bytes) | Type |
| type=10 | 1 | unsigned char |
| .bof File Name | variable | string |
- STATUS
Packet type identifier = 20 (decimal)
Total Length: 2 Bytes
| Name | Size (bytes) | Type |
| type=20 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
- LISTCMD
Packet type identifier = 30 (decimal)
Total Length: 2 Bytes
| Name | Size (bytes) | Type |
| type=30 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
- LISTBOF
Packet type identifier = 35 (decimal)
Total Length: 2 Bytes
| Name | Size (bytes) | Type |
| type=35 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
- LISTDEV
Packet type identifier = 40 (decimal)
Total Length: 2 Bytes
| Name | Size (bytes) | Type |
| type=40 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
- READ
Packet type identifier = 50 (decimal)
Total Length: 10 + len(register_name) Bytes
| Name | Size (bytes) | Type |
| type=50 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| Start Offset | 4 | unsigned int |
| num_bytes | 4 | unsigned int |
| register_name | variable | string |
- INDEXEDREAD
Packet type identifier = 51 (decimal)
Total Length: 11
| Name | Size (bytes) | Type |
| type=51 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| Start Offset | 4 | unsigned int |
| num_bytes | 4 | unsigned int |
| register_index | 1 | unsigned char |
- WRITE
Packet type identifier = 60 (decimal)
Total Length: 10 + len(register_name) + len(data) Bytes
| Name | Size (bytes) | Type |
| type=60 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| Start Offset | 4 | unsigned int |
| num_bytes | 4 | unsigned int |
| register_name | variable | string (null terminated) |
| data | variable | raw_binary |
- INDEXEDWRITE
Packet type identifier = 61 (decimal)
Total Length: 10 + len(data)
| Name | Size (bytes) | Type |
| type=61 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| Start Offset | 4 | unsigned int |
| num_bytes | 4 | unsigned int |
| register_index | 1 | unsigned char |
| data | variable | raw_binary |
- EXEC
Packet type identifier = 70 (decimal)
Total Length: 2 + len(command) Bytes
| Name | Size (bytes) | Type |
| type=70 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| command | variable | string |
Returned Packets
- ERR
Packet type identifier = 110
Total Length: 2 + len(error_message) Bytes
| Name | Size (bytes) | Type |
| type=110 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| error_msg | variable | string |
- REPORT
Packet type identifier = 120
Total Length: 2 + len(status_message) Bytes
| Name | Size (bytes) | Type |
| type=120 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| status_msg | variable | string (null terminated) |
- AVAILCMND
Packet type identifier = 130
Total Length: 2 + len(commands) Bytes
| Name | Size (bytes) | Type |
| type=130 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| command_name1 | variable | string (null terminated) |
| command_name2 | variable | string (null terminated) |
| command_name3 | variable | string (null terminated) |
| ... | ... | ... |
| command_nameN | variable | string (null terminated) |
- AVAILBOF
Packet type identifier = 135
Total Length: 2 + len(filenames) Bytes
| Name | Size (bytes) | Type |
| type=130 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| bof_executable_1 | variable | string (null terminated) |
| bof_executable_2 | variable | string (null terminated) |
| bof_executable_3 | variable | string (null terminated) |
| ... | ... | ... |
| bof_executable_N | variable | string (null terminated) |
- AVAILDEV
Packet type identifier = 140
Total Length: 2 + len(device names) Bytes
| Name | Size (bytes) | Type |
| type=140 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| device_name1 | variable | string (null terminated) |
| device_name2 | variable | string (null terminated) |
| device_name3 | variable | string (null terminated) |
| ... | ... | ... |
| device_nameN | variable | string (null terminated) |
- DATA
Packet type identifier = 160
Total Length: 2 + len(data) Bytes
| Name | Size (bytes) | Type |
| type=160 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| data | variable | raw_binary |
- EXECREPORT
Packet type identifier = 170
Total Length: 4 Bytes
| Name | Size (bytes) | Type |
| type=170 | 1 | unsigned char |
| ID tag | 1 | unsigned char |
| PID | 2 | 16b int |