Assignment 2: I2C Simulator - V1.02

Transcription

1 Assignment 2: I2C Simulator - V1.02 Due Wednesday February 22 nd, 2012 by 11:59 pm. Submit deliverables via CourSys: Late penalty is 10% per calendar day (each 0 to 24 hour period past due). Friday, February 24 th is the last possible day to submit (11:59 pm). This assignment may be done either individually or in pairs. Do not show other students your code, do not copy code found online, and do not post questions about the assignment online. Please direct all questions to the instructor or TA: cmpt-212-help@sfu.ca; See the marking guide for details on how each part will be marked. 0. I2C Background In this assignment you'll be creating a program which can work with some simplified I 2 C bus transactions (often written as I2C). I2C (Inter-Integrated Circuit) is communication protocol for sending small pieces of information between a processor (called the master) with one or more slave devices. For example, your PC likely uses this protocol to communicate with the real-time clock component and the temperature sensors on your motherboard. It is designed to be a simple protocol which allows for lowspeed data between inexpensive components. Figure 1 shows a possible bus configuration. Slave 0x24 Slave 0x51 Slave 0xA9 Master I 2 C Bus Figure 1: I2C bus topology with one master and three slave devices. 0.1 I2C Transactions All transactions are initiated by the master. Each slave has a unique address to which it responds. Each transaction transmits the following data: <Device Address>,<R W>,<Data byte(s)> Device Address: The address of the slave device with which the master will be communicating. The address for a specific component is assigned when the slave is manufactured. R W (Read/Write): Indicates if the master wants to read data from the slave, or write data to the slave. Data: For a write, it is the data the master is transmitting to the slave. For a read, it is the data the slave transmits back to the master. Note that I2C includes a low-level protocol which uses two wires (called SCL and SDA), and transmits data using special signaling on these wires. For this assignment, we are not concerned with this level of the protocol; we'll described data at a logical level in terms of what is transmitted, not how it is transmitted. If you look up I2C, you will likely find information on the low-level signaling. Generated Feb 15, 2012, 11:16 PM Page 1/12 Dr. Fraser

2 0.2 Registers Each device has up to 256 registers (numbered 0 through 255) which can be accessed via I2C. Each register is 8 bits (one byte). Each slave device can have certain registers serve special purposes. You can think of registers as mail boxes which can hold information. For example, a temperature sensor might use register 0x01 to hold the current temperature it is reading. And register 0x02 may be used to configure its operation. In general, the function of each register is defined by its manufacturer. Depending on the device, some registers may allow the master to write a value into it, whereas other registers may not allow a value to be written (more on this later). 0.3 Write Transactions When the master write data into a register of a slave device, the transaction is as follows: <Device Address>,W,<Register Address> <Data to write> Note that this fits with the format mentioned earlier: the first value of <Data> is the register to write to. When <Data to write> is one byte, that value is written into the register stated. For example: 11,W,AB 42 This will write the value 0x42 to register 0xAB on slave device 0x11. When there is more than one byte of data to write, the device will start at the stated register and continue working through registers as needed. The device keeps writing to registers one after the next as the master sends it more data. If it reaches register 255, it wraps around and starts writing at register 0. For example: 11,W,AB will write data as summarized in Table 1. Note that the values in this example are arbitrary. I2C Address Reg 0xAB Reg 0xAC Reg 0xAD Reg 0xAE 0x11 0x42 0x52 0x62 0x72 Table 1: Explanation of the multi-byte write command. 0.4 Read Transaction Read transactions with I2C have two parts. First, the master writes a register number to the slave but does not send any data; then, the master reads a certain number of bytes of data from the slave. In this assignment, there are two different way that reads by the master may be seen. First, your system may be queried with a read request. In which case, it must return the expected data. The following two statements represent the command to read: <Device Address>,W,<Register Address> <Device Address>,R,<Number of Bytes to Read> For example, the master may want to read 2 bytes, starting at register 0x04 of slave address 0xF2. And, let's say that the slave is holding 0x80 in register 0x04, and 0x62 in register 0x05: F2,W,04 F2,R,02 The slave would then output the two bytes 0x80 and 0x62. The second way that a read can happen for this assignment is when you are processing a full transaction that was previously recorded. This is the analysis command, and is explained in Part 2. Generated Feb 15, 2012, 11:16 PM Page 2/12 Dr. Fraser

3 1. I2C Slave Simulations Write a program to simulate the operation of a group of I2C slave devices. Each slave will have a unique I2C address, and can have up to 256 one-byte registers (numbered 0 through 255). Each register can be written to, or read from by the master. Your program will accept, via the command line, the name of a text file which contains I2C commands. Your program will process the commands: for write commands, it will update the values stored in the register(s) of the slave device; for read commands it will read the content of the register(s) and display it to the screen. The input file has one command per line. Lines which start with a '#' are comments and should be ignored. Blank lines, or lines containing only whitespace (spaces, tabs,...) should also be ignored. 1.1 Command File Format: Write The format for write commands is: <I2C Address>,W,<Register> <Data> I2C Address: a 2 digit hex number. W: signifies that this is a write command. Register: 2 digit hex number for the register. Data: a space separated list of 2 digit hex numbers of the data to write to the registers. Each hex number is of the form such as 01, or AB. No "0x" precedes the values. See note in Section 0.3 for what to do when writing more than one byte Examples (see simple_write.txt): 11,W,AB 42 11,W, ,W, Command File Format: Read The format for a read has two parts (as described in Section 0.4 ): <I2C Address>,W,<Register> <I2C Address>, R,<Number Bytes To Read> The write statement sets the register number to work with. The read statement reads a number of bytes, starting at the previously set register. Simulate reading by outputting the data to the screen. See sample runs in Section Example (see simple_readwrite.txt): 11,W,AB 11,R,01 11,W,60 11,R,01 11,W,00 11,R,04 Generated Feb 15, 2012, 11:16 PM Page 3/12 Dr. Fraser

4 1.3 Summary Report Print a summary report to the screen when your program finishes. It should display the status of all registers of known slave devices. 1. If there is more than one slave device, they may be listed in any order (need not be sorted). 2. The registers for a specific device must be displayed in ascending order (sorted). Note that the QMap will sort its entries by the key, so sorting should not be a problem. See the implementation constraints below for use of QMap. 3. For each register, display the register number and its current value (i.e. final value) Summary report for simple_write.txt D:\212\As2-build-desktop\debug>As2.exe simple_write.txt Processing I2C Log file: Tests/simple_write.txt Completed processing file with 0 errors. I2C Simulator Full Report ************************* I2C Device 0x11: Reg 0x00 current value 0x11 Reg 0x01 current value 0x22 Reg 0x02 current value 0x33 Reg 0x03 current value 0x44 Reg 0x60 current value 0x01 Reg 0xab current value 0x Implementation Constraints 1. Write your program in C++ using the Qt libraries. Do not use any code from the C++ std library (i.e., don't have a "using namespace std;", don't #include <string> or <iostream>...) 2. Conform to the coding style guide on the course website. 3. Handle any combination of I2C addresses and register addresses: Addresses can be between 0 and 255 (0x00 and 0xFF). Register can be numbers between 0 and 255 (0x00 and 0xFF). 4. Do not preallocate slave devices or registers before they are needed. If only one slave, and one register on that device are used, your program should not consume extra memory for the unused devices and unused registers. You can implement this as follows: Initially, your simulation should include no slave devices; they are added as needed. When a command uses a new I2C address (for read, write, or (later) analysis), create a new slave device for that address. When a new slave device is added, it will initially have no registers. If a read command uses a register that does not yet exist, just return 0xFF without creating the register. When a command writes to a non-existent register on a slave device, create the register. Generated Feb 15, 2012, 11:16 PM Page 4/12 Dr. Fraser

5 5. Implementation requirements for data storage: Use a QList to hold pointers to dynamically allocated slave devices. For each slave device, use a QMap to store its registers. You must use delete to free all dynamically allocated memory before your program finishes. Do not rely on the operating system to clean up the memory for you. 6. Recall that read commands ("R") need the register number to be set by a preceding write command. Read commands to a slave will read from the register that the last write command used. You may assume that all read commands to a device will occur after a write to the device, and that write's data was just the register number. For example, you may assume reads occur in the following valid pattern:: 11,W,10 11,R,04 The following is INVALID in many ways; the behaviour of your program can be undefined (we will not test this: read before write, more than just register in the write, multiple reads): 11,R,04 11,W, ,R,04 11,R,04 7. Implementation Suggestions: To convert the hexadecimal string "A5" into a number, use QString's toint() function. Look at the documentation for a overloaded version which accepts a base (base 16 for hex). To convert the number 42 into a hexadecimal QString, use the following code: // 42: Value to convert // 2: Number of digits // 16: Base for conversion (hex) // QChar('0'): Character to fill for extra digits (5 becomes "05") QString asstr = QString("%1").arg(42, 2, 16, QChar('0')); 8. Use iterators wherever possible, and you must use each style of iterator at least once. Do not use direct-access loops for QList or QMap; use an iterator. For example, avoid: // BAD! Use an iterator! for (int i = 0; i < mylist.size(); i++) { cout << mylist[i]; } You must use each of the three styles of iterator at least once. - C++ STD style: such as QList<int>::iterator itr = mylist.begin(); - Java style: such as QListIterator<int> itr(mylist); - Qt foreach: such as foreach (const int &value, mylist) {...} 9. Use exceptions to handle errors while parsing and processing the input file. Create one exception class to throw when there is an error parsing a line in the file. For example, throw it when the command is 'X' but should be one of 'R', 'W', or 'A'. Make this exception class hold a QString error message. Create one exception class to throw when there is a warning when processing an analysis Generated Feb 15, 2012, 11:16 PM Page 5/12 Dr. Fraser

6 command (see Section 2.4 ). Make this exception class also hold an error message. Have your code which is iterating through the input file catch these errors and print out the message string in the exception, along with the line number and full line of text from the input file. See examples in Section 1.5 for more information. 1.5 Sample Runs Bold-underlined text shows command-prompt input Run without arguments D:\212\As2-build-desktop\debug>As2.exe Usage: As2.exe <commandfile> Example: As2.exe i2ccommands.txt Processing read and write commands D:\212\As2-build-desktop\debug>As2.exe simple_readwrite.txt Processing I2C Log file: simple_readwrite.txt Reading from Address [0x11], Register[0xab] = 0x42 Reading from Address [0x11], Register[0x60] = 0x01 Reading from Address [0x11], Register[0x00] = 0x11 Reading from Address [0x11], Register[0x01] = 0x22 Reading from Address [0x11], Register[0x02] = 0x33 Reading from Address [0x11], Register[0x03] = 0x44 Reading from Address [0x11], Register[0x10] = 0xff Reading from Address [0x11], Register[0x11] = 0xff Reading from Address [0x11], Register[0x12] = 0xff Reading from Address [0x11], Register[0x13] = 0xff Reading from Address [0x11], Register[0xfe] = 0xff Reading from Address [0x11], Register[0xff] = 0xff Reading from Address [0x11], Register[0x00] = 0x11 Reading from Address [0x11], Register[0x01] = 0x22 Reading from Address [0x11], Register[0x02] = 0x33 Reading from Address [0x11], Register[0x03] = 0x44 Reading from Address [0x11], Register[0x04] = 0xff Reading from Address [0x11], Register[0x05] = 0xff Completed processing file with 0 errors. I2C Simulator Full Report ************************* I2C Device 0x11: Reg 0x00 current value 0x11 Reg 0x01 current value 0x22 Reg 0x02 current value 0x33 Reg 0x03 current value 0x44 Reg 0x60 current value 0x01 Reg 0xab current value 0x42 Generated Feb 15, 2012, 11:16 PM Page 6/12 Dr. Fraser

7 1.5.3 Processing read and write commands D:\212\As2-build-desktop\debug>As2.exe multi_readwrite.txt Processing I2C Log file: multi_readwrite.txt Reading from Address [0x10], Register[0x80] = 0x10 Reading from Address [0x10], Register[0x81] = 0x11 Reading from Address [0x10], Register[0x82] = 0x12 Reading from Address [0x10], Register[0x83] = 0x13 Reading from Address [0x20], Register[0x80] = 0x20 Reading from Address [0x20], Register[0x81] = 0x21 Reading from Address [0x20], Register[0x82] = 0x22 Reading from Address [0x20], Register[0x83] = 0x23 Reading from Address [0x30], Register[0x80] = 0x30 Reading from Address [0x30], Register[0x81] = 0x31 Reading from Address [0x30], Register[0x82] = 0x32 Reading from Address [0x30], Register[0x83] = 0x33 Completed processing file with 0 errors. I2C Simulator Full Report ************************* I2C Device 0x10: Reg 0x80 initial value 0x10 current value 0x10 Reg 0x81 initial value 0x11 current value 0x11 Reg 0x82 initial value 0x12 current value 0x12 Reg 0x83 initial value 0x13 current value 0x13 I2C Device 0x30: Reg 0x80 initial value 0x30 current value 0x30 Reg 0x81 initial value 0x31 current value 0x31 Reg 0x82 initial value 0x32 current value 0x32 Reg 0x83 initial value 0x33 current value 0x33 I2C Device 0x20: Reg 0x80 initial value 0x20 current value 0x20 Reg 0x81 initial value 0x21 current value 0x21 Reg 0x82 initial value 0x22 current value 0x22 Reg 0x83 initial value 0x23 current value 0x23 Generated Feb 15, 2012, 11:16 PM Page 7/12 Dr. Fraser

8 1.5.4 Handling parse errors Your error messages do not need to match perfectly with the messages shown below. However, your program should behave similarly for each line of the input file. D:\212\As2-build-desktop\debug>As2.exe test_errors.txt Processing I2C Log file: test_errors.txt PARSING ERROR on line 19: Missing data. Line 19 = ','. PARSING ERROR on line 20: Unable to convert hex string '' to a number. Line 20 = ',,'. PARSING ERROR on line 21: Extra data on line. Line 21 = ',,,'. PARSING ERROR on line 22: Missing direction (R/W). Line 22 = '10'. PARSING ERROR on line 26: Unable to convert hex string 'zz' to a number. Line 26 = 'zz,w,1'. PARSING ERROR on line 27: Value out of range. Must be between 0 and 255. Value: 200. Line 27 = '200,W,1'. PARSING ERROR on line 28: Value out of range. Must be between 0 and 255. Value: -1. Line 28 = '-1,W,1'. PARSING ERROR on line 31: Unable to convert hex string 'Hello' to a number. Line 31 = '00,W,Hello world!'. PARSING ERROR on line 32: Value out of range. Must be between 0 and 255. Value: 200. Line 32 = '00,W,200'. PARSING ERROR on line 33: Value out of range. Must be between 0 and 255. Value: -1. Line 33 = '00,W,-1'. PARSING ERROR on line 36: Extra data on line. Line 36 = '1,W,3,4,5,6'. PARSING ERROR on line 37: Missing data. Line 37 = '1,W'. PARSING ERROR on line 40: Missing direction (R/W). Line 40 = 'It's the end of the world as we know it.'. PARSING ERROR on line 41: Missing direction (R/W). Line 41 = 'I feel fine.'. PARSING ERROR on line 44: Unknown command. Expecting 'W', 'R', or 'A'. Line 44 = '10,X,11 12'. PARSING ERROR on line 47: Missing data. Line 47 = '10,W'. PARSING ERROR on line 48: Missing data. Line 48 = '10,R'. PARSING ERROR on line 51: Read expects only the number of bytes to read. Line 51 = '10,R,10 11'. Completed processing file with 18 errors. I2C Simulator Full Report ************************* I2C Device 0x10: Generated Feb 15, 2012, 11:16 PM Page 8/12 Dr. Fraser

9 2. I2C Slave Analysis This part adds extra functionality to the system you implemented for reading and writing I2C slave registers. Make sure you have the previous part working before continuing. 2.1 Background There are tools ("sniffers") which capture and log transactions on an I2C bus. Consider a working I2C system with a master and some slave devices. The sniffer would log all the transactions, capturing many read and write commands sent to the different slave devices. Imagine that you want to create a new super-slave device which simulates the operation of multiple slave devices. For example, you want to replace three slave devices with a single new slave device that makes the master think it is still working with the original three slaves The system from Part 1 does most of this by process write requests, and responding to read requests for all possible I2C addresses and registers. However, in order to create the replacement superslave device, you'll first need to analyze the transactions that are normally occurring on the bus. During this analysis, there are two important things to look out for: 1. What is the initial value in each register? So far, we have assumed that all registers start with the value 0xFF. However, in a real system, some registers will hold different values to start with. For example, one register may be the device's serial number, and another may its default configuration. Therefore, when the master reads from either of these two registers it will get a value other than 0xFF. We need to be able to look at the log of transactions and infer the initial value for each register. 2. Are there any registers that don't behave like simple read/write registers? There are some registers that will be simple read/write registers. These registers will start with some initial value, and only change their value when the master writes a new value to them. However, there are other registers which may change their value on their own (such as a register reporting the current time), or which may be read-only (such as the serial number for a device). We need to be able to look at the log of transactions and identify any registers which either change their value on their own, or which do not change their value when written to. 2.2 Command File Format: Analysis To perform this analysis, we'll introduce the analysis command ("A"). The analysis command is very similar to a read, in that it needs a preceding write to setup the register number. However, instead of it asking your program for the data, your program is given the data that a real I2C slave device replied with. Its format is: <Address>,W,<Register> <Address>,A,<Data> Address: The I2C address of the device. A: Indicate that this command is for an analysis. Data: A space separated list of 2-digit hex numbers representing the data that the real slave device replied with to the master. The following two sections describe the analysis to be performed on the data. Generated Feb 15, 2012, 11:16 PM Page 9/12 Dr. Fraser

10 2.3 Inferring Register Initial Value Change your program to handle not only write and read, but also also analysis commands: 1. For each register in each slave device, store both its initial value and its current value. 2. If the first command to access a register is an analysis command ("A"), then set the register's initial value (and current value) to the data in the command. 3. Whenever there is a write to a register, update only its current value field to the new value. 4. If there is a write to a register before there is an analysis command for it, then just set the register's initial value to whatever value is being written. (We have to record something as the initial value, and we don't have any way of determining what it actually was). 5. If there is a read from a register before it is referenced by an analysis or write commands, then just return 0xFF (without creating the register). 6. Change the program's summary report to also include the initial value for each register. See example below Using an analysis command to infer initial value Display of file analysis_simple.txt # Infer value via analysis (single byte) 81,W,C1 81,A,00 81,W,C1 81,R,1 # Test multiple bytes: 81,W,B0 81,A, ,W,B0 81,R,4 Program execution: D:\212\As2-build-desktop\debug>As2.exe analysis_simple.txt Processing I2C Log file: analysis_simple.txt Reading from Address [0x81], Register[0xc1] = 0x00 Reading from Address [0x81], Register[0xb0] = 0x20 Reading from Address [0x81], Register[0xb1] = 0x21 Reading from Address [0x81], Register[0xb2] = 0x22 Reading from Address [0x81], Register[0xb3] = 0x23 Completed processing file with 0 errors. I2C Simulator Full Report ************************* I2C Device 0x81: Reg 0xb0 initial value 0x20 current value 0x20 Reg 0xb1 initial value 0x21 current value 0x21 Reg 0xb2 initial value 0x22 current value 0x22 Reg 0xb3 initial value 0x23 current value 0x23 Reg 0xc1 initial value 0x00 current value 0x00 Generated Feb 15, 2012, 11:16 PM Page 10/12 Dr. Fraser

11 2.4 Reporting Behaviour problems For each analysis command ("A"), if a register already holds a current value, then check if its current value matches the value in the analysis command's data. If they do not match then do both: 1. Update the current value to be the value in the analysis command's data. 2. Generate an exception indicating that there was an analysis problem. This is an analysis exception, not a parsing exception, so use new exception classes. Have the exception store a message explaining the problem (see examples below). If the analysis command has multiple bytes of data, make sure it processes all the bytes before an exception is thrown Using an analysis command to infer initial value Input File: analysis_simple2.txt # Read-only register (should generate warning). 10,W,35 B5 10,W,35 10,A,E0 # Three read-only registers (should generate warning). 10,W,45 D1 D2 D3 10,W,45 10,A,C1 C2 C3 # Register changes on its own (generates warning) 10,W,A0 10,A,00 10,W,A0 10,A,01 Program execution: D:\212\As2-build-desktop\debug>As2.exe analysis_simple2.txt Processing I2C Log file: analysis_simple2.txt ANALYSIS PROBLEM on line 6: Register 0x35 mismatch: holds 0xb5 but expected 0xe0. Line 6 = '10,A,E0'. ANALYSIS PROBLEM on line 11: Register 0x45 mismatch: holds 0xd1 but expected 0xc1. Register 0x46 mismatch: holds 0xd2 but expected 0xc2. Register 0x47 mismatch: holds 0xd3 but expected 0xc3. Line 11 = '10,A,C1 C2 C3'. ANALYSIS PROBLEM on line 18: Register 0xa0 mismatch: holds 0x00 but expected 0x01. Line 18 = '10,A,01'. Completed processing file with 3 errors. I2C Simulator Full Report ************************* I2C Device 0x10: Reg 0x35 initial value 0xb5 current value 0xe0 Reg 0x45 initial value 0xd1 current value 0xc1 Reg 0x46 initial value 0xd2 current value 0xc2 Reg 0x47 initial value 0xd3 current value 0xc3 Reg 0xa0 initial value 0x00 current value 0x01 Generated Feb 15, 2012, 11:16 PM Page 11/12 Dr. Fraser

12 3. Testing The website contains some sample input files for testing. You will be submitting all your.h and.cpp files. The TA will be using the following sequence of commands to build them your system. You should ensure that your code will build. 1. Copy.h and.cpp files into a new folder names as2 on the CSIL Linux machines in SUR Copy the provided test files into the same folder. 3. Build a Qt project file (.pro): > qmake -project 4. Create a project makefile: > qmake 5. Build the project: > make 6. Run your program with an input file: >./as2 simple_readwrite.txt 4. Deliverables Submit a zip file named as2.zip containing just your.h and.cpp files to CourSys: You do not need to submit a makefile, a Qt project file, or any test files. Each of your.cpp and.h files must begin with a comment stating your name, your SFU user ID, and your SFU student number. (If in a pair, state both your information). If you are working in a pair: only submit one copy of the assignment, include a PAIRS.TXT file listing the name, SFU ID and student number of each of you. Please remember that all submissions will automatically be compared for unexplainable similarities. 5. Change History Feb 13: Revised section 0.4 to discuss the read command from the file, vs the general I2C read. Restated how the application should behave when reading/writing/analyzing registers and slaves that do not exist. Generated Feb 15, 2012, 11:16 PM Page 12/12 Dr. Fraser