You are here: HomeTutorialsTutorial 1 - A Serial Communication FPGA Debug Module Tutorial 1: Part 4 - Java Software Specification and Design (Part 1)

Tutorial 1: Part 4 - Java Software Specification and Design (Part 1)

1.4.1 Introduction

0000435aThe aim of this part of the series  is to create a boilerplate FPGA Serial Communication Debug Module Application, using the Java programming language.  The NetBeans Integrated Development Environment (IDE) will be used for the application development. The application will be used to send and receive messages from a FPGA Serial Debug Module, embedded in a FPGA. 

When developing software it is good practice to derive a specification of how the software will operate. Also, in the case of Graphical User Applications (GUIs), how they look and feel. So to begin with a description of the application is presented.

1.4.2 Software Specification

The application software is required to develop an application to send messages and receive responses from an FPGA debug module using the RS232 serial communications protocol. On start up the application should allow the user to select the communications port that the FPGA module is connected to. It is expected that the application will need to enumerate the serial ports, to identify which serial ports are available. If the user has successfully connected to the FPGA debug module it should be indicated by a yet TBD method. 

Sent messages can be of two different types, which are either a register type message or a user defined type message. Each type of message is described in more detail below.

A message that is sent as a register type message consists of three fields of information. These are an op-code, a register number and a 32-bit value, which is typically hexadecimal. In a typical mode of operation, to read a register the op-code is set to 0x03 and to write to a register the op-code is set to 0x01. However, when regression testing, the firmware in the FPGA module, the application should be placed in test mode. In this mode the op-code can have any value between 0x00 and 0xFF. Also, in this mode incomplete message can be sent. 

The second type of message, the user defined type, also consists of three fields. These are an op-code, the number of bytes to transmit and the bytes to transmit, which must be checked to ensure the total number of bytes sent matches the number of bytes field. The op-code of the user defined message should be 0x05. The number of bytes sent, in a user defined message, should be limited to between  1 and 255.

0000435

Figure 1.4.1: A "back of the envelope" drawing of the proposed FPGA Serial Communication Debug Module Application user interface layout. 

For all message types, clicking on the send button transmits the message. If all the fields of a message are valid, the message is transmitted to the FPGA debug module using the RS232 serial communications protocol.  Each byte of a message is transmitted with an active low start bit, 8 data bits, an active high stop bit and no parity bits. When the serial line is idle it is expected to be at an active high logic level. No hardware flow control is used.

Responses can also be received from the FPGA debug module. Received responses can be of three types, a register type response, a user defined type response and an error type response. If a response is not one of these three types it should be logged as an unknown type of response. A register type response should consist of three fields beginning with an op-code, that has a value of 0x03. A register number and a 32-bit value, which should typically be hexadecimal, are the other parts of the register type.

The format of a  user defined type response is made up of an op-code, the number of bytes read and the byte values. The op-code of the user defined message should be 0x06. The number of bytes read, from the FPGA debug module, should be between 1 and 255. 

Finally, an error type response consists of the following format. An op-code value of 0x05 is followed by an error code value, which should be limited to between 1 and 255. The error messages are TBD, however the error responses are typically expected to be displayed in textual format in the GUI. For example, if an error code  of 0x01 means that the register number is unknown, then the textual string, "ERR_UNKNOWN_REGISTER_NUM", should be used to represent that error code.

A log window of sent messages and received responses should be used to display colour coded messages and responses, depending on the message, or response, type. A diagram of what th eGUI could look like can be seen, in Figure 1.4.1,  above.

1.4.3 The Graphical User Interface (GUI)

The software design approach taken is to abstract the user interface design away from the functions that send messages and receive responses. The two separate entities, the graphical user interface and the transceiver functions, are only allowed to interact through the use of access functions.

The first part of the design tackled is the GUI, which is based upon the specifications above. The GUI has been designed using Java Swing control components, including JPanel, JLabel, JtextBox, JMenu and others. 

0000436

Figure 1.4.2The proposed FPGA serial debug program user interface.

1.4.2 Data Dictionary - Identifying Classes, Member Functions and Data Members

A data dictionary is used to fully understand the functional and data requirements of the application software. It is used to identify functions and data variables, as well as the relationships between the two. A data dictionary, that could be used, is developed in the following paragraphs.

The application software, <Class FPGASerialDebugModuleUI> is required to develop an application to send messages <sendMessage()> and receive responses <receiveResponse()> from an FPGA debug module using the RS232 serial communications protocol. On start up the application should allow the user to select the communications port <selectPort()> that the FPGA module is connected to. It is expected that the application will need to enumerate <serachPorts()> the serial ports, to identify which serial ports are available.  If the user has successfully connected <connect()> to the FPGA debug module it should be indicated by a yet TBD method and the user should then initialise the event, or activity, listener <initListener()> for the port.

Sent messages <Class sendMessage> can be of two different types, which are either a register type message <Class RegisterMsg> or a user defined type message <Class UserDefinedMsg>. Each type of message is described in more detail below.

A message that is sent as a register type message consists of three fields of information. These are an op-code <unsigned char opcode>,register number, <unsigned char regNum> and a 32-bit value, <unsigned int value> which is typically hexadecimal. In a typical mode, <setTypicalMode()> of operation, to read a register the op-code is set to 0x03 and to write to a register the op-code is set to 0x01. However, when regression testing, the firmware in the FPGA module, the application should be placed in test mode, <setTestMode()>. In this mode the op-code can have any value between 0x00 and 0xFF. Also, in this mode incomplete messages can be sent.

A prototype register message type class can be seen in the code fragment below. Note that Java does not support unsigned types. Hence, to work around Java's lack of support, it is recommended to use a type that is bigger than the unsigned type required.

 

 class RegisterMsg { 
    int opcode = 0x00; // In C++ this would be an unsigned char.
    int regNum= 0x00;     // In C++ this would be an unsigned char.
    long value = 0;    // In C++ this would be an unsigned int.
    void receive() {
         ..................
    }
    void transmit() {
         ...................
    }
}

 

The second type of message, the user defined type, also consists of three fields. These are an op-code, <unsigned char opcode, the number of bytes,  <numBytes>to transmit and the bytes to transmit, <bytesToTransmit>, which must be checked, <checkNumBytes()>, to ensure the total number of bytes sent matches the number of bytes in the numnber of bytes field. The op-code of the user defined message should be 0x05. The number of bytes sent, in a user defined message, should be limited to between  and 255.

For all message types, clicking on the send button transmits, <transmit()> the message. If all the fields of a message are valid, <isValid()>, the message is transmitted to the FPGA debug module, using the RS232 serial communications protocol.  Each byte of a message is transmitted with an active low start bit, 8 data bits, an active high stop bit and no parity bits. When the serial line is idle it is expected to be at an active high logic level. No hardware flow control is used.

Responses can also be received from the FPGA debug module, by the application software. Received responses,  <Class receiveResponse> can be of three types, a register type response, a user defined type response and an error type, <Class ErrorMsg>, response. If a response is not one of these three types it should be logged as an unknown type, <Class UnknownMsg> of response. A register type response should consist of three fields beginning with an op-code, that has a value of 0x03. A register number and a 32-bit value, which should typically be hexadecimal, are the other parts of the register type.

The format of a  user defined type response is made up of an op-code, the number of bytes read and the byte values. The op-code of the user defined message should be 0x06. The number of bytes read, from the FPGA debug module, should be between and 255

Finally, an error type response consists of the following format. An op-code value of 0x05 is followed by an error code , <errorCode>, value, which should be limited to between 1 and 255. The error messages are TBD, however the error responses are typically expected to be displayed in textual format in the GUI. For example, if an error code  of 0x01 means that the register number is unknown, then the textual string, "ERR_UNKNOWN_REGISTER_NUM", should be used to represent that error code.

A log window of sent messages and received responses should be used to display colour coded messages and responses, depending on the message, or response, type. A diagram of what the GUI could look like can be seen, in Figure 1.4.1,  above. When the user exits <exit()>from the program, the program  the serial port must be disconnected <disconnect()>

0000437

Figure 1.4.3The proposed class structure of the Java application software.

 

As described previously, the aim of writing the application software is to provide communication between a FPGA and a PC. The FPGA contains a serial debug module, whose status registers can be displayed in the application software's Graphical User Interface (GUI). The GUI is also used to set the debug module's control registers and drive logic connected to them too.

The structure of the FPGA serial debug module's software can be seen, in Figure 1.4.4, below. The GUI is used to drive the FPGASerialDebugModule class which utilises the register, user defined and error type classes. Also, the class is used in conjuntion with an event driven listener, reader function and a threaded writer function.

The third-party RXTX Java serial communications library is used to provide the link between the application and the CP2102 device drivers. It is these virtual comms drivers that provide communication with the CP2102 device and hence the outside world.

0000440

Figure 1.4.4The structure of the FPGASerialDebugModule application software, written in Java.

 

1.4.3 Aftermath

Before continuing with the development of the Java application software there are one or two other factors that need to be taken into account first. Primarily, we need to consider how to verify the hardware. Ideally, we should use any application software developed, as part of the hardware test harness and hence the dilemma.

If Modelsim's Foreign Language Interface (FLI) is considered to be the tool to use, to verify the hardware design, then a cosimulation environment would require development in C/C++. It could also mean, to save development time, that the application software should be written in C/C++ too. Previously, the choice of development environment had been a "toss-up" between using Java and Netbeans or C/C++ and QT.

If Java is used to develop the application software, then at some stage during the hardware/software cosimulation development, Java's Remote Method Invocation (RMI) interface will have to be used. This may add an extra, and possibly unnecessary,  level of complication to our verification environment.

To address this dilemma, over which programming  language to use to develop the application software,  the  next part of the tutorial  will consider how the FLI can be used to verify the hardware already written. Overall, there are three stages required to complete this tutorial,  writing the remaining FPGA design entities, developing the application software and writing the verification environemt.

If Java is used to write the application software, then this part of the tutorial is likely to be continued as "Java Software Specification and Design (Part 2)". However, as stated previously, verification and the FLI will be considered in the  next part of the tutorial and we should be able to develop a FLI application.

Go to comments start