Software Development Project - Selection of Appropriate Planning Tools and Development Language - Lab Report Example

Software Development Project Word Search game By A Project Report Submitted in Partial Fulfillment of the Requirements for the Degree In Your Major Approved: n (enter appropriate #) Semester Credits _________________________________ Place the name of your research adviser here. Your adviser signs on the line. Castle College, Nottingham Higher National in Computing Month, Year HN Computing (Software Development) Program No.: F5044 HNC Computing (Software Development) F5045 HND Computing (Software Development) Unit Code: 20903V Assessment No.: 2 Unit Leader: Roger horn Internal Verifier: Martin Heeley Version: 20/10/2006 TABLE OF CONTENTS 1. INTRODUCTION 4 2. SCOPE 5 3. ANALYSIS OF THE PROBLEM 5 4. SPECIFICATIONS 6 5. SELECTION OF APPROPRIATE PLANNING TOOLS 7 6. SELECTION OF APPROPRIATE DEVELOPMENT LANGUAGE 8 7. IMPLEMENTATION 11 8. TESTING 12 9. EVALUATION 12 10. CONCLUSION 13 KNOWN SHORT COMINGS FUTURE ENHANCEMENTS 11. DISCUSSION ON THE SUCCESS OF THE PROJECT 13 12. BIBLIOGRAPHY 15 13. SOURCE CODE 16 14. APPENDIX A 17 WEEKLY PLAN 15. APPENDIX B 23 REFERENCE MANUAL 16. POWER POINT PRESENTATION 50 INTRODUCTION As the technology matures and as its implications are worked out we identify ways to implement and manage it. There are a variety of categories and disciplines we could address. My main concentration is area relating to application of Microsoft VC++. The project concentrates on utilizing the MS VC++ to the fullest and bring out its wonderful application in the selected topic WORD SEARCH GAME. As the name itself explains we are trying to locate the word from a word square. The user puts forth a collection of words, which are to be selected. The program works at the background and the logic written tries to find the word entered from the word square, the words detected gets highlighted blue in colour. Once the word is found the users collection vanishes. Searching of the word is in all directions (Vertical, Horizontal, diagonal.). All this is devised into a GUI (Graphical User Interface). Buttons like RESET, EXIT is created to facilitate the user to start afresh with the searching. Once all the words are searched the user is appraised with messages. The main motto is to make it capable to run on any machine with Microsoft package at Standalone. SCOPE: The project is in partial fulfillment of the Degree addressing everyone who is interested to use its application and also for those who are interested in studying its technical where about. ANALYSIS OF THE PROBLEM In literary terms the word entered by the user is to be stored at a location and be searched in the word square (GRID) with various combinations. Technically storing, retrieving and displaying requires following tasks in no particular order: 1. The word entered needs to be stored in an array. 2. A structure, which stores all the letters of the Grid. 3. Implementing a logic that compares the array of the word with the letters of the Grid in all the possible ways. 4. Any empty space in the grid should be filled with a random letter. 5. The size of the word entered is to be checked. 6. The colour of the word searched to be changed. 7. Refreshing or redoing the whole process once RESET button is pressed. 8. Come out of the program or the game if EXIT button is pressed. 9. Final message of success or failure to be displayed. 10. Should be able to present using GUI. SPECIFICATIONS: (Minimum Requirements) Processor: 600MHz. RAM: 192MB. Available Hard disk Space: 1GB on system drive, 2GB on Installation Drive. Operating System: Windows 2000 service Pack 4, Windows XP Service Pack Windows Server 2003 Service Pack 1,Windows vista. For a 64-Bit Computer: Windows Server 2003 Service Pack 1X64 Editions. Windows XP Professional X 64 Editions Video: 800X600, 256 colours. Mouse: Microsoft mouse or compatible pointing Device. SELECTION OF APPROPRIATE SOFTWARE PLANNING TOOLS A wide range of Software Planning tools are available but the following two are considered in particular due to their flexibility in adaption and some of the following reas The above analysis over the two opted software suggests us to select Microsoft Project 2003 package. SEELCTION OF APPROPRIATE DEVELOPMENT LANGUAGE The software that is suitable to my project are many but to my knowledge Java, Borland Delphi and VC++ seemed feasible. When researched over their properties I could find that all the three are visual development packages with RAD (Rapid Action Development) capabilities. They feature an IDE (Integrated Development Environment) with features such as drag-and-drop of GUI building blocks and integrated debugging support. There is little to choose among the three with respect to IDE. The following advantages/disadvantages being considered: Language Advantages Disadvantages Java Object-oriented Distributed Interpreted Robust Secure Architecture neutral Portable Multithreaded Dynamic Does not support real-time programming Speed to run the applications Microsoft Visual C++ Object oriented language. Help easily available. Very powerful debugger. There is an ANSI standard so the language cannot change. Code is cryptic. Hard to learn. Slow compilation times. Poor type checking. Poor range checking. Easy to write errors in the code. Borland Delphi Rapid Application Development (RAD) Based on a well-designed language - high-level and strongly typed, with low-level escapes for experts Can compile to a single executable, simplifying distribution and reducing DLL versioning issues Many VCL and third-party components (usually available with full source code) and tools (documentation, debug tools, etc.) Class helpers to bridge functionality available natively in the Delphi RTL, but not available in a new platform supported by Delphi The languages object orientation features only class- and interface-based polymorphism Limited cross-platform capability for Delphi itself. Compatibles provide more architecture/OS combinations Access to platform and third party libraries require header files to be translated to Pascal. This creates delays and introduces the possibilities of errors in translation. There are fewer published books on Delphi than on other popular programming languages such as C++ and C# A reluctance to break any code has lead to some convoluted language design choices, and orthogonality and predictability have suffered IMPLEMENTATION: UML diagram: Explanation of the UML diagram generated for the projects says (Algorithm): Initially a randomly selected words fit in the Word Square whose creation is clearly stated in the source code. The word entered by the user is stored in an array. A logic written which is stated in the source code compares each letter in the array to the letter in the grid to see if they form the word needed. Two conditions arise: 1. If yes is the answer of the logic the word matched changes its colour to blue and the already entered word by the user automatically vanishes. 2. If no is the answer of the logic a message is shown as no match found. Two more options are given for user-friendly application RESET and EXIT. 1. RESET: Starts the game all over again. 2. EXIT: Comes out of the loop and terminates the program giving an END Message. TESTING The complexity of the project is more in its programming than in Tesiting. So, the testing is done manually possing on various options to the program. It is tested thoroughly by checking through a checklist as follows: Are the letters being filled randomly in the grid? (YES). Are the buttons giving the effect expected? (YES). Is the output screen legible to user? (YES). Is program working for every word put forth? (YES). Are the empty spaces in the grid filled randomly after the searched words have vanished? (YES). Is the program working under standalone mode? (YES). Is the source code according to the standards of Microsoft? (YES). Every function internal and external is checked by possing different values. Testing if interested can be done using a Testing Tool Win Runner EVALUATION The project is evaluated by testing it thoroughly and proofread several times by eminent people who have a sound knowledge over the topic. CONCLUSION KNOWN SHORT COMINGS: Many letters entered in the Grid remain unused which results in wastage of storage space in the memory. After a number of words being searched and replaced the Grid may become redundant. FUTURE ENHANCEMENTS: In future the project is expected to be implemented as to allow the user to form a dynamic grid and try to writer a word intelligently searching from the grid. This not only makes it interesting but also helps users to hone their language skills. The logic implemented can be used to implement the game in other programming languages. A DISCUSSION ON THE SUCCESS OF THE PROJECT: Projects are many for a student to choose from for the completion of semester. I had a thought to implement a much challenging programming language to a simplest of applications, which had a much more implication to day-to-day life. Such as a word search game. Thorough study about the availability of various software packages and programming languages was done. The comparison and mode of selection of the preferred Microsoft package and Micro soft VC++ programming language is clearly stated in the report in the sections Appropriate Software Planning tools and Appropriate Developing Language. The analysis of the problem gave idea as to what steps should be followed in writing the source code. A UML diagram devised gave the complete picture of the task at hand. The source code this written is attached in the appendix, which is bugs, free and ready to use. The success of the project made me realize the programming skills I have and where do I stand in generating a source code. I am enthusiastic to do another project, which may be an enhancement to this. BIBLIORAPHY David, N. Erin Karper. (17/05/2007). March, 13, 2007, http://owl.english.purdue.edu/owl/resource/560/01. Duchess, W. (n.d) .12/05/2000. PlanBee Pro. March, 13, 2007, http://www.guysoftware.com/planbee.htm. F.D.I. (n.d). Software Developer user Manuals. February, 04, 2007, http://www.teamfdi.com/products/downloads/support/manual. Microsoft (1997). Specifications. January, 01 , 2007, http://msdn2.microsoft.com/en-us/visualc/default.aspx. Philips Joseph. (n.d). Software Project Management, Mc Graw Hill Publications, 11, 7-10. Roger, S. (2002). Software Engineering: A Practitioner’s Approach, Mc Graw Hill publications. SOURCE CODE: Appendices Appendix A Weekly Plan: Fig.: 1 Fig.:2 Fig.:3 Fig.:4 Fig.: 5 Fig.:6 Appendix B User manual Software Developer User Manual FDIFuture Designs, Inc.Your Development Partner Information in this document is provided solely to enable the use of Future Designs, Inc. products. FDI assumes no liability whatsoever, including infringement of any patent or copyright. FDI reserves the right to make changes to these specifications at any time, without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Future Designs, Inc. 2702 Triana Blvd SW, Huntsville, AL 35805-4074.  2004 Future Designs, Inc. All rights reserved. Microsoft, MS-DOS, Windows, Microsoft Word are registered trademarks of Microsoft Corporation. Other brand names are trademarks or registered trademarks of their respective owners. P:\PC PRoducts\PC-I2C\Docs\PC-I2C-DEV User Manual 3_E.doc, Revision 3.E, 3/11/2004 1:01 PM Printed in the United States of America i Table of Contents 1. PC-I2C-DEV Overview......................................................................................1 2. PC-I2C-DEV Installation...................................................................................1 3. Using the PC-I2C-DEV in a VC++ Project........................................................2 4. Three Example VC++ Projects..........................................................................4 5. General Purpose Routines................................................................................5 5.1 DriverAgentOpen.........................................................................................5 5.2 DaOpenDevice............................................................................................5 5.3 DaCloseDevice............................................................................................5 5.4 DriverAgentClose........................................................................................5 5.5 SetupHardware...........................................................................................6 5.6 DetectHardware..........................................................................................6 6. I2C Routines.....................................................................................................7 6.1 I2cReadSCL................................................................................................7 6.2 I2cDropSCL.................................................................................................7 6.3 I2cRaiseSCL...............................................................................................7 6.4 I2cReadSDA................................................................................................7 6.5 I2cDropSDA................................................................................................7 6.6 I2cRaiseSDA...............................................................................................8 6.7 I2cGenerateStartCondition..........................................................................8 6.8 I2cGenerateRepeatedStartCondition..........................................................8 6.9 I2cGenerateStopCondition..........................................................................8 6.10 I2cWriteByte..............................................................................................8 6.11 I2cReadByte..............................................................................................9 6.12 I2cWriteDevice..........................................................................................9 6.13 I2cReadDevice..........................................................................................9 6.14 I2cReadMemory......................................................................................10 6.15 I2cWriteMemory......................................................................................10 6.16 I2cReadMemory16..................................................................................11 6.17 I2cWriteMemory16..................................................................................12 7. MDIO Routines...............................................................................................13 7.1 MdioReadMDC..........................................................................................13 7.2 MdioDropMDC...........................................................................................13 7.3 MdioRaiseMDC.........................................................................................13 7.4 MdioReadMDIO.........................................................................................13 7.5 MdioDropMDIO.........................................................................................13 7.6 MdioRaiseMDIO........................................................................................14 7.7 MdioSendBits............................................................................................14 7.8 MdioReadBits............................................................................................14 7.9 MdioSendPreamble...................................................................................14 7.10 Mdio22ReadWord...................................................................................15 7.11 Mdio22WriteWord....................................................................................15 7.12 Mdio45ReadWord...................................................................................16 7.13 Mdio45WriteWord....................................................................................16 i i 8. SPI Routines...................................................................................................17 8.1 SpiReadDIN..............................................................................................17 8.2 SpiDropDOUT...........................................................................................17 8.3 SpiRaiseDOUT..........................................................................................17 8.4 SpiReadCLK..............................................................................................17 8.5 SpiDropCLK..............................................................................................17 8.6 SpiRaiseCLK.............................................................................................18 8.7 SpiDropCS................................................................................................18 8.8 SpiRaiseCS...............................................................................................18 8.9 SpiShiftReg...............................................................................................18 8.10 SpiClockWait...........................................................................................19 9. System Definitions..........................................................................................20 9.1 Function Return Values.............................................................................20 9.2 nLoopsPerUsec Determination..................................................................20 9.3 NLoopsPerUsec Estimated Values...........................................................21 ii i 1. PC-I2C-DEV Overview The PC-I2C-DEV Software Developer Kit contains all of the tools necessary to access and control the PC-I2C hardware from a custom application. The PC-I2C-DEV can be used with Visual C/C++ or any other programming language that supports the use of DLLs. (Note that the PC-I2C-DEV was generated and tested using Microsoft Visual C/C++ 6.0, but there is no reason that it will not work in all Microsoft Windows software development environments such as Borland C/C++, Microsoft Visual Studio, or any programming software which utilizes DLL.) The PC-I2C-DEV consists of the following: • A complete PC-I2C-KIT which includes o An FDI Installation and Support CDROM o PC-I2C Board with PCF8582 EEPROM o 4-pin connecting cable (18” length) o PC-I2C-KIT Quick Start Manual o Registration form for the PC-I2C parallel port adapter • PC-I2C-DEV Software Developer Installation CDROM o Three user configurable DLL examples • PC-I2C-DEV Software Developer User Manual 2. PC-I2C-DEV Installation Insert the PC-I2C-DEV Installation CDROM into the proper drive. If the setup program does not automatically run, open the PC-I2C-DEV Installation CDROM from “My Computer” and run “setup.exe” by double-clicking on it. Follow the instructions on the subsequent screens. When the installation is completed, the computer will have to be re-booted in order for the installation to complete. The Setup.exe program installs the files needed for the standard operation of the PC-I2C-KIT and those needed to add PC-I2C functionality to a custom application. The required .DLL and .SYS files will be copied to the appropriate system directories and the required modifications to the registry will be made. The remaining files will be copied into the following subdirectories (Assuming that the default directories were used during the installation procedure). • C:\Program Files\FDI\PC-I2C – This directory contains the standard PC-I2C application and help files. • C:\Program Files\FDI\PC-I2C\DDF – This directory contains the Device Descriptor Files (DDF) used by the standard PC-I2C-KIT software. See the PC-I2C software on-line help for details. • C:\Program Files\FDI\PC-I2C\SDF – This directory contains the Sequence Descriptor Files (DDF) used by the standard PC-I2C-KIT software. See the PC-I2C software on-line help for details. 1 • C:\Program Files\FDI\PC-I2C\DEV – This directory contains the files that must be used by your custom application to access the PC-I2C hardware. This subdirectory also contains the electronic version of this user manual. • C:\Program Files\FDI\PC-I2C \DLL_Example – This directory contains a Microsoft VC++ example project that can be used to verify that the PC-I2C hardware and software are functioning properly. • C:\Program Files\FDI\PC-I2C \DTMF_Interface – This directory contains a Microsoft VC++ example project that will interface with any PCD3311C or PCD3312C compatible musical-tone generator. • C:\Program Files\FDI\PC-I2C \LCD_Interface – This directory contains a Microsoft VC++ example project that will interface with any PCF21xxC family compatible LCD Driver. 3. Using the PC-I2C-DEV in a VC++ Project In order to add the functionality of the PC-I2C-DEV to a custom application, you must perform the following steps. Note that you can use the example project located in the DLL_Example subdirectory as a reference for implementing these steps. 1. Make sure that the PC-I2C-DEV installation program was run from the installation disk. This program installs the software and makes the modifications to the registry that are needed for proper operation of the PC-I2C-DEV. 2. Copy the following files from the \DEV subdirectory (C:\Program Files\FDI\PC-I2C\DEV if the default installation location was used) to the directory that contains the source code for your custom application. a. Pport_Proxy.lib b. DriverAgent.lib c. Pport_Proxy.h d. DriverAgent.h e. Remap.h 3. In the VC++ environment, add the .lib files to your project by opening the “Project” menu, selecting “Add to Project”, and clicking on “Files”. Select the following files from the dialog box and click “OK”. a. Pport_Proxy.lib b. DriverAgent.lib 4. Add the following line to each of the files in your project that will access the PC-I2C software: #include “Pport_Proxy.h” 2 5. Create a global variable that will hold the handle of the PC-I2C device as follows: HCLIENTDEVICE g_hPCI2C = NULL; 6. During your application’s initialization, add the following PC-I2C kernel initialization code: DEVSTATUS devStatus = DEVSTATUS_SUCCESS ; if ( API_SUCCESS(devStatus=DriverAgentOpen()) ) { // Open the "PPort" device devStatus=DaOpenDevice(_TEXT("PPort"), &g_hPCI2C, NULL); } 7. Setup the PC-I2C hardware. SetupHardware( CPU_SPEED, PULSE_WIDTH, PORT_ADDR); 8. Call the PC-I2C-DEV routines as needed to perform the desired tasks. 9. When your application terminates, release the handle to the PC-I2C resources. // Release the "PCI2C" handle if it exists if ( g_hPCI2C ) DaCloseDevice(g_hPCI2C) ; // Close the Kernel mode driver DriverAgentClose() ; 3 4. Three Example VC++ Projects The subdirectory “DLL_Example” contains an example project created with the Microsoft VC++ 6.0 MFC application wizard. The example project shows how to interface a custom application to the PC-I2C-DEV software to access the on-board PCF8582C I2C EEPROM. The subdirectory “DTMF_Interface” contains an example project created with the Microsoft VC++ 6.0 MFC application wizard. The example project shows how to interface a custom application to the PC-I2C-DEV software to access a PCD3312P DTMF Generator. The subdirectory “LCD_Interface” contains an example project created with the Microsoft VC++ 6.0 MFC application wizard. The example project shows how to interface a custom application to the PC-I2C-DEV software to access a PCF21xxC family LCD Driver. 4 5. General Purpose Routines These routines are used to initialize, setup, and terminate the PC-I2C DLL functionality. They are usually called only once by the custom application. 5.1 DriverAgentOpen Prototype: DEVSTATUS DriverAgentOpen(void) Function: This routine is called to start the Kernel Mode driver that controls the parallel port. It should be called once during the custom application’s initialization. Parameters: None Returns: None 5.2 DaOpenDevice Prototype: DEVSTATUS DaOpenDevice( PCSTR pszName, HCLIENTDEVICE *phDevice, PCLIENTDEVICEINFO pClientInfo ) Function: This routine is called to get a handle to the Kernel Mode driver’s parallel port resource. It should be called once during the custom application’s initialization after calling DriverAgentOpen(). Parameters: pszName phDevice pClientInfo Returns: None 5.3 DaCloseDevice Prototype: DEVSTATUS DaCloseDevice( HCLIENTDEVICE *hDevice) Function: This routine is called to release the handle to the Kernel Mode driver’s parallel port resource. It should be called once during the custom application’s shutdown procedure before calling DriverAgentClose(). Parameters: hDevice Returns: None 5.4 DriverAgentClose Prototype: void DriverAgentClose( void) Function: This routine is called to terminate the Kernel Mode driver that controls the parallel port. It should be called once during the custom application’s shutdown procedure. 5 Parameters: None Returns: None 5.5 SetupHardware Prototype: int SetupHardware( int nLoopsPerUsec, int n50Percent, int nPort) Function: This routine is called to set up the parameters to be used by the PC-I2C hardware. It should be called once during the custom application’s initialization. The parameters nLoopsPerUsec and n50Percent are used to determine the effective bus speed. The value of nLoopsPerUsec can be calculated using the code in the example or can be estimated from the chart that is provided later in this manual. Parameters: nLoopsPerUsec – Number of loops the processor executes in a uSec. n50Percent – Fifty times the desired clock period in uSec. For example, a 100kHz clock would yield 500 (50*1/100,000) nPort – The hardware address of the Parallel Port that is being used by PC-I2C (e.g. 0x378, 0x3bc, etc.) Returns: Always returns a 0x00 5.6 DetectHardware Prototype: int DetectHardware( void) Function: This routine is called to detect the presence of the PC-I2C hardware on the parallel port. This routine can be called at any time. Parameters: None Returns: Returns TRUE if the board was detected and FALSE if it was not detected. 6 6. I2C Routines These routines are used to support the I2C bus protocol. There are routines included to perform low level bit manipulation as well as routines to send entire messages across the I2C bus. 6.1 I2cReadSCL Prototype: int I2cReadSCL( void) Function: This routine returns the current state of the SCL line of the I2C interface. Parameters: None Returns: “0” if SCL is low, “1” if SCL is high 6.2 I2cDropSCL Prototype: int I2cDropSCL( void) Function: This routine forces the SCL line of the I2C interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 6.3 I2cRaiseSCL Prototype: int I2cRaiseSCL( void) Function: This routine forces the SCL line of the I2C interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 6.4 I2cReadSDA Prototype: int I2cReadSDA( void) Function: This routine returns the current state of the SDA line of the I2C interface. Parameters: None Returns: “0” if SDA is low, “1” if SDA is high 6.5 I2cDropSDA Prototype: int I2cDropSDA( void) Function: This routine forces the SDA line of the I2C interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 7 6.6 I2cRaiseSDA Prototype: int I2cRaiseSDA( void) Function: This routine forces the SDA line of the I2C interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 6.7 I2cGenerateStartCondition Prototype: int I2cGenerateStartCondition( void) Function: This routine generates a start condition on the I2C interface. Parameters: None Returns: Always returns I2C_NO_ERROR 6.8 I2cGenerateRepeatedStartCondition Prototype: int I2cGenerateRepeatedStartCondition( void) Function: This routine generates a repeated start condition on the I2C interface. Parameters: None Returns: Always returns I2C_NO_ERROR 6.9 I2cGenerateStopCondition Prototype: int I2cGenerateStopCondition( void) Function: This routine generates a stop condition on the I2C interface. Parameters: None Returns: Always returns I2C_NO_ERROR 6.10 I2cWriteByte Prototype: int I2cWriteByte( int nByte) Function: This function transmits a single byte to the I2C bus. It assumes that the bus is available, that the proper Start Condition has previously been generated, and that the slave device has been properly addressed. Parameters: nByte – The byte to write to the I2C interface. Returns: Returns I2C_NO_ACK if the slave device does not acknowledge the byte. Otherwise it returns I2C_NO_ERROR. 8 6.11 I2cReadByte Prototype: int I2cReadByte( int *nByte, int nLast) Function: This function reads a single byte from the I2C bus. It assumes that the bus is available, that the proper Start Condition has previously been generated, and that the slave device has been properly addressed. If the parameter nLast is FALSE, an ACK is generated after the byte is transmitted. Otherwise, no ACK is generated. The result of the read is saved in *nByte. Parameters: *nByte – This is a pointer to the location that receives the byte read from the I2C bus. nLast – This parameter determines if an ACK should be generated after the byte is transmitted. If nLast is FALSE, an ACK is generated. If nLast is TRUE, no ACK is generated. Returns: Always returns I2C_NO_ACK. Also updates the value pointed to by nByte with the byte read from the I2C bus. 6.12 I2cWriteDevice Prototype: int I2cWriteDevice( int nDeviceAddress, int nCount, int nBuffer[], int nRegWidth = 1) Function: This function is used to write a complete message to the I2C bus. It handles generation of the Start and Stop Conditions as well as properly addressing the Slave device. Parameters: nDeviceAddress – The I2C bus address of the slave device. nCount – The number of words to write to the slave device. nBuffer[] – A buffer that contains the bytes to write to the slave device. nRegWidth – The width of each register and thus each word. Returns: Returns I2C_NO_ACK if the slave device fails to acknowledge any of the bytes that are transmitted. Otherwise returns I2C_NO_ERROR. 6.13 I2cReadDevice Prototype: int I2cReadDevice( int nDeviceAddress, int nCount, int nBuffer[], int nRegWidth = 1) Function: This function is used to read a complete message from the I2C bus. It handles generation of the Start and Stop Conditions as well as properly addressing the Slave device. It also generates an ACK for every byte transmitted except for the final one. (This is a common method of terminating a read process on the I2C bus.) 9 Parameters: nDeviceAddress – The I2C bus address of the slave device. nCount – The number of words to read from the slave device. nBuffer[] – A buffer that receives the bytes read from the slave device. nRegWidth – The width of each register and thus each word. Returns: Returns I2C_NO_ACK if the slave device fails to acknowledge its address. Otherwise returns I2C_NO_ERROR. It also updates the contents of nBuffer with the read results. 6.14 I2cReadMemory Prototype: int I2cReadMemory( int nDeviceAddress, int nMemoryAddress, int nCount, int nBuffer[], int nRegWidth = 1 ) Function: This function reads a block of memory from an I2C memory device using 11-bit internal addressing. It handles the generation of the Start and Stop Conditions as well as properly addressing the Slave device. It also handles setting up the proper address to read and the proper ACK sequence for the read procedure. Parameters: nDeviceAddress – The I2C bus address of the slave device. nMemoryAddress – The address within the slave device to begin reading. nCount – The number of words to read from the slave device. (A maximum of 0x100 bytes can be read at a time.) nBuffer[] – A buffer that receives the bytes read from the slave device. nRegWidth – The width of each register and thus each word. Returns: Returns I2C_NO_ACK if the slave device fails to acknowledge its address or the memory address to read. Returns I2C_COUNT_TOO_BIG if a number larger than 0x100 is read in nCount. Otherwise returns I2C_NO_ERROR. It also updates the contents of nBuffer with the read results. 6.15 I2cWriteMemory Prototype: int I2cWriteMemory( int nDeviceAddress, int nMemoryAddress, int nCount, int nBuffer[], int nRegWidth = 1 ) 1 0 Function: This function writes a block of memory to an I2C memory device using 11-bit internal addressing. It handles the generation of the Start and Stop Conditions as well as properly addressing the Slave device. It also handles setting up the proper address to write. Parameters: nDeviceAddress – The I2C bus address of the slave device. nMemoryAddress – The address within the slave device to begin writing. nCount – The number of words to write to the slave device. (A maximum of 0x10 bytes can be written at a time.) nBuffer[] – A buffer that contains the bytes to write to the slave device. nRegWidth – The width of each register and thus each word. Returns: Returns I2C_NO_ACK if the slave device fails to acknowledge any of the bytes written to it. Returns I2C_COUNT_TOO_BIG if a number larger than 0x10 is read in nCount. Otherwise returns I2C_NO_ERROR. 6.16 I2cReadMemory16 Prototype: int I2cReadMemory16( int nDeviceAddress, int nMemoryAddress, int nCount, int nBuffer[], int nRegWidth = 1 ) Function: This function reads a block of memory from an I2C memory device using 19-bit internal addressing. It handles the generation of the Start and Stop Conditions as well as properly addressing the Slave device. It also handles setting up the proper address to read and the proper ACK sequence for the read procedure. Parameters: nDeviceAddress – The I2C bus address of the slave device. nMemoryAddress – The address within the slave device to begin reading. nCount – The number of words to read from the slave device. (A maximum of 0x10000 bytes can be read at a time.) nBuffer[] – A buffer that receives the bytes read from the slave device. nRegWidth – The width of each register and thus each word. Returns: Returns I2C_NO_ACK if the slave device fails to acknowledge its address or the memory address to read. Returns I2C_COUNT_TOO_BIG if a number larger than 0x10000 is read in nCount. Otherwise returns I2C_NO_ERROR. It also updates the contents of nBuffer with the read results. 1 1 6.17 I2cWriteMemory16 Prototype: int I2cWriteMemory16( int nDeviceAddress, int nMemoryAddress, int nCount, int nBuffer[], int nRegWidth = 1 ) Function: This function writes a block of memory to an I2C memory device using 19-bit internal addressing. It handles the generation of the Start and Stop Conditions as well as properly addressing the Slave device. It also handles setting up the proper address to write. Parameters: nDeviceAddress – The I2C bus address of the slave device. nMemoryAddress – The address within the slave device to begin writing. nCount – The number of words to write to the slave device. (A maximum of 0x10 bytes can be written at a time.) nBuffer[] – A buffer that contains the bytes to write to the slave device. nRegWidth – The width of each register and thus each word. Returns: Returns I2C_NO_ACK if the slave device fails to acknowledge any of the bytes written to it. Returns I2C_COUNT_TOO_BIG if a number larger than 0x10 is read in nCount. Otherwise returns I2C_NO_ERROR. 1 2 7. MDIO Routines 7.1 MdioReadMDC Prototype: int MdioReadMDC( void) Function: This routine returns the current state of the MDC line of the MDIO interface. Parameters: None Returns: “0” if MDC is low, “1” if MDC is high 7.2 MdioDropMDC Prototype: int MdioDropMDC( void) Function: This routine forces the MDC line of the MDIO interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 7.3 MdioRaiseMDC Prototype: int MdioRaiseMDC( void) Function: This routine forces the MDC line of the MDIO interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 7.4 MdioReadMDIO Prototype: int MdioReadMDIO( void) Function: This routine returns the current state of the MDIO line of the MDIO interface. Parameters: None Returns: “0” if MDIO is low, “1” if MDIO is high 7.5 MdioDropMDIO Prototype: int MdioDropMDIO( void) Function: This routine forces the MDIO line of the MDIO interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 1 3 7.6 MdioRaiseMDIO Prototype: int MdioRaiseMDIO( void) Function: This routine forces the MDIO line of the MDIO interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 7.7 MdioSendBits Prototype: int MdioSendBits( int nData, int nCount ) Function: This routine transfers any number of bits (up to 32) on the MDIO interface by placing the bit on the bus and transitioning the clock. Parameters: nData – The data pattern to transmit. Bits are transmitted starting with the least significant bit. nCount – Number of bits to transmit. Returns: Always returns I2C_NO_ERROR 7.8 MdioReadBits Prototype: int MdioReadBits( int *nData, int nCount ) Function: This routine reads any number of bits (up to 32) from the MDIO interface. Parameters: nData – Value that receives the result of the read operation. nCount – Number of bits to read. Returns: Always returns I2C_NO_ERROR. Also updates the value of nData with the bits read from the bus. 7.9 MdioSendPreamble Prototype: int MdioSendPreamble( void) Function: This routine transmits 32 high bits on the MDIO interface to create the preamble that is required by the MDIO specification. Parameters: None Returns: Always returns I2C_NO_ERROR. 1 4 7.10 Mdio22ReadWord Prototype: int Mdio22ReadWord( int nPhyAddr, int nRegAddr, int *nData ) Function: This routine reads a single 32bit word from the MDIO (Clause 22) interface. The resultant word is returned in the variable nData. Parameters: nPhyAddr – This value is the address of the slave device on the MDIO bus. nRegAddr – This is the address of the register within the slave device that is to be read. nData – This is the location that will receive the results of the read operation. Returns: Always returns I2C_NO_ERROR. Also updates the value of nData with the value read from the bus. 7.11 Mdio22WriteWord Prototype: int Mdio22WriteWord( int nPhyAddr, int nRegAddr, int nData ) Function: This routine writes a single 32bit word to the MDIO (Clause 22) interface. Parameters: nPhyAddr – This value is the address of the slave device on the MDIO bus. nRegAddr – This is the address of the register within the slave device that is to be written. nData – This is the data that will be written to the slave device. Returns: Always returns I2C_NO_ERROR. 1 5 7.12 Mdio45ReadWord Prototype: int Mdio45ReadWord( int nPortAddr, int nDevAddr, int nRegAddr, int *nData ) Function: This routine reads a single 32bit word from the MDIO (Clause 45) interface. The resultant word is returned in the variable nData. Parameters: nPortAddr – This value is the address of the slave device on the MDIO bus. nDevAddr – This is the device page address of the slave device. nRegAddr – This is the address of the register within the slave device that is to be read. nData – This is the location that will receive the results of the read operation. Returns: Always returns I2C_NO_ERROR. Also updates the value of nData with the value read from the bus. 7.13 Mdio45WriteWord Prototype: int Mdio45WriteWord( int nPortAddr, int nDevAddr, int nRegAddr, int nData ) Function: This routine writes a single 32bit word to the MDIO (Clause 24) interface. Parameters: nPortAddr – This value is the address of the slave device on the MDIO bus. nDevAddr – This is the device page address of the slave device. nRegAddr – This is the address of the register within the slave device that is to be written. nData – This is the data that will be written to the slave device. Returns: Always returns I2C_NO_ERROR. 1 6 8. SPI Routines 8.1 SpiReadDIN Prototype: int SpiReadDIN( void) Function: This routine returns the current state of the DIN line of the SPI interface. Parameters: None Returns: “0” if DIN is low, “1” if DIN is high 8.2 SpiDropDOUT Prototype: int SpiDropDOUT( void) Function: This routine forces the DOUT line of the SPI interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 8.3 SpiRaiseDOUT Prototype: int SpiRaiseDOUT( void) Function: This routine forces the DOUT line of the SPI interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 8.4 SpiReadCLK Prototype: int SpiReadCLK( void) Function: This routine returns the current state of the CLK line of the SPI interface. Parameters: None Returns: “0” if CLK is low, “1” if CLK is high 8.5 SpiDropCLK Prototype: int SpiDropCLK( void) Function: This routine forces the CLK line of the SPI interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 1 7 8.6 SpiRaiseCLK Prototype: int SpiRaiseCLK( void) Function: This routine forces the CLK line of the SPI interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 8.7 SpiDropCS Prototype: int SpiDropCS( void) Function: This routine forces the CS line of the SPI interface low. Parameters: None Returns: Always returns I2C_NO_ERROR 8.8 SpiRaiseCS Prototype: int SpiRaiseCS( void) Function: This routine forces the CS line of the SPI interface high. Parameters: None Returns: Always returns I2C_NO_ERROR 8.9 SpiShiftReg Prototype: int SpiShiftReg( int OutGoing[], int WordWidth, int InComing[], int UseCS ) Function: This routine takes the value from OutGoing[] and shifts it out on DOUT while storing the value shifted in from DIN to Incoming[]. Parameters: int OutGoing[] – This value is the command to be shifted out to the target device. int WordWidth – This value is the width of the command in bits. int InComing[] – This value is the data shifted in from DIN during transmission of the command. int UseCS – This value is the polarity of the CS line during transmission. “0” signifies that CS should be high during transmission. “1” signifies that CS should be low during transmission. “2” signifies that CS is not applicable. Returns: Always returns I2C_NO_ERROR. The information shifted in on DIN is stored in InComing[]. 1 8 8.10 SpiClockWait Prototype: int SpiClockWait( BOOL WaitForValue, int WaitClocks, int UseCS ) Function: This routine forces the CS line of the SPI interface high. The CS line is held in this state until a logic value matching WaitForValue is read on DIN. When this is read, or SpiClockWait has waited an amount of time equal to WaitClocks number of clocks, the function will return I2C_NO_ERROR. Parameters: BOOL WaitForValue – The logic value on the DIN line which specifies that SpiClockWait should return. int WaitClocks – The number of clocks to count before SpiClockWait should give up and return regardless of the value on the DIN line. int UseCS – This value is the polarity of the CS line during transmission. “0” signifies that CS should be high during transmission. “1” signifies that CS should be low during transmission. “2” signifies that CS is not applicable. Returns: Always returns I2C_NO_ERROR 1 9 9. System Definitions This section contains miscellaneous system definitions and notes for using the PC-I2C-DEV. 9.1 Function Return Values The following values can be returned by the Developer Kit routines. They are returned by the SPI and MDIO routines as well as the I2C routines. These values are declared in the Pport_Proxy.h file. • I2C_NO_ERROR – Functions return this value if no error occurs. This is the standard return value. • I2C_NO_ACK – Functions return this value when the slave device fails to acknowledge a byte that was transferred over the bus. • I2C_COUNT_TOO_BIG – Functions return this value when the amount of data to move is too large for the internal buffers. 9.2 nLoopsPerUsec Determination The value of the parameter nLoopsPerUsec, which is used by the SetupHardware() routine, is used to specify the processing speed of the host computer. This value can be calculated directly, using the code snippet below, or can be estimated from values given in the table. // // Determine nLoopsPerUsec value // LARGE_INTEGER Freq, Start, Finish; _int64 HPAverage = 0; _int64 HPDiff = 0; _int64 HPusec = 0; int nCount = 0; QueryPerformanceFrequency( &Freq); // Loop 10 times for (int j=0; j Read More