WinCE6.0 I2C SMDKV210 Revision 1.00 October 2010 2010 Samsung Electronics Co., Ltd. All rights reserved.
Important Notice The information in this publication has been carefully checked and is believed to be entirely accurate at the time of publication. Samsung assumes no responsibility, however, for possible errors or omissions, or for any consequences resulting from the use of the information contained herein. Samsung reserves the right to make changes in its products or product specifications with the intent to improve function or design at any time and without notice and is not required to update this documentation to reflect such changes. This publication does not convey to a purchaser of semiconductor devices described herein any license under the patent rights of Samsung or others. Samsung makes no warranty, representation, or guarantee regarding the suitability of its products for any particular purpose, nor does Samsung assume any liability arising out of the application or use of any product or circuit and specifically disclaims any and all liability, including without limitation any consequential or incidental damages. "Typical" parameters can and do vary in different applications. All operating parameters, including "Typicals" must be validated for each customer application by the customer's technical experts. Samsung products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, for other applications intended to support or sustain life, or for any other application in which the failure of the Samsung product could create a situation where personal injury or death may occur. Should the Buyer purchase or use a Samsung product for any such unintended or unauthorized application, the Buyer shall indemnify and hold Samsung and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, expenses, and reasonable attorney fees arising out of, either directly or indirectly, any claim of personal injury or death that may be associated with such unintended or unauthorized use, even if such claim alleges that Samsung was negligent regarding the design or manufacture of said product. Copyright 2010 Samsung Electronics Co., Ltd. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electric or mechanical, by photocopying, recording, or otherwise, without the prior written consent of Samsung Electronics. Samsung Electronics Co., Ltd. San #24 Nongseo-Dong, Giheung-Gu Yongin-City, Gyeonggi-Do, Korea 446-711 Contact Us: junghwan.shin@samsung.com TEL: (82)-(31)-209-6277 FAX: (82)-(31)-209-1973 Home Page: http://www.samsungsemi.com Printed in the Republic of Korea
Revision History Revision No. Date Author(s) 1.00 Jun. 03. 2010 Modified for WinCE Chow Kim 0.10 Dec. 02. 2008 Initial draft SSPTS Team
Table of Contents 1 INTRODUCTION... 7 1.1 Purpose... 7 1.2 Scope... 7 1.3 Intended Audience... 7 1.4 References... 7 2 I2C DRIVER... 8 2.1 Introduction... 8 2.2 Driver Structure... 8 2.3 State Diagram... 9 2.4 Processing Flow... 10 2.5 Software Interface... 12 2.6 Sample Code... 13 2.7 Debug Information... 13 3 I2C EMULATION LIBRARY... 14 3.1 Introduction... 14 3.2 Software Interface... 14 3.3 Sample Code... 16 3.3.1 Simple Function... 16 3.3.2 Combination Function... 16 3.4 Debug Information... 16
List of Figures Figure Title Page Number Number Figure 2-1 I2C Stream Driver Structure... 9 Figure 2-2 State Diagram of the Driver... 10 Figure 2-3 Processing Flow of the Driver... 11
List of Tables Table Title Page Number Number Table 2-1 Software Interface of the I2C Driver... 12 Table 3-1 Software Interface of the I2C Emulation Library... 14
1 INTRODUCTION 1 INTRODUCTION 1.1 Purpose The purpose of the document is to describe the I2C Driver and I2C emulator library for easy portability into different platforms by developers. I2C driver can be used for devices that connected to dedicated I2C GPIOs. I2C emulator library can be used for devices that connected to General GPIOs instead of dedicated I2C GPIOs.I2C driver is based on stream driver, that is to say you can use CreateFile(), ReadFile(), and WriteFile(), etc. 1.2 Scope The scope of this document is to describe I2C driver and I2C emulator library Software architecture of I2C driver Software interface Sample code and debug information 1.3 Intended Audience Intended Audience Project Manager Project Leader Project Team Member Test Engineer Tick whenever Applicable Yes Yes Yes Yes 1.4 References Number Reference 1 SMDKV210_WinCE6.0_FMD_PortingGuide.doc OS porting guide 2 S5PC110_UserManual.pdf Device user manual 7
2 I2C DRIVER 2 I2C DRIVER 2.1 Introduction I2C driver is following I2C-BUS SPEC V2.1 It is designed for multi-thread environment Logical and physical layer are separated, both can be operated independently. The driver interface is compatible to I2C_EMUL stream driver. Users don t need to consider if the hardware interface is I2C or I2C Emulator. It provides debug information, and supports error recovery. I2C driver sends stop control when error occurs. It supports almost every slaves and customer functions for special slaves. User can open I2C driver with wanted speed. So that each slave can have its own speed. It is tested with PMIC, AUDIO CODEC, CAMERA MODULE and HDMI. You can check sample code. 2.2 Driver Structure Below picture shows the driver structure. There is no limitation about number of Group. A registry entry of I2C in platform.reg file creates public object If a client driver opens i2c, It makes private object. And the handle includes public object. The public has phead and ptail, phead points the first element of private and the ptail points the final element of private All privates have pnext and pprev, pnext points next element and pprev points previous element 8
2 I2C DRIVER Figure 2-1 I2C Stream Driver Structure 2.3 State Diagram It is based on state machine The first step is that master receives one byte through state transition The second step is that master sends one byte through state transition The blue box appears Thread State and the gray circle appears Object state. 9
2 I2C DRIVER Figure 2-2 State Diagram of the Driver 2.4 Processing Flow Bellow picture shows flow of processing. Client driver requests to I2CWrapper I2Cwrapper files up item into the state machine. I2Cwrapper passes I2CObject to the I2CHWCtxt. I2CHWCtxt set event and I2C thread receive this event. I2C thread is getting item from the state machine. I2C thread is processing When I2C thread finish its operation, it sets DONE event I2CHWCtxt returns value. I2CWrapper returns result. 10
2 I2C DRIVER Figure 2-3 Processing Flow of the Driver 11
2 I2C DRIVER 2.5 Software Interface IOCTL function is provided for accessing I2C functionalities. You can use DeviceIOControl() function to access I2C functionalities with proper IO Control Code. Here are the IO Control Code descriptions. Table 2-1 Software Interface of the I2C Driver IO Control Code Initialize I2C, have to set slave address and speed typedef struct _I2C_INIT_DESC { IOCTL_I2C_INIT WORD IN_wSlaveAddr; DWORD IN_dwClockSpeed; DWORD OUT_dwActualSpeed; } I2C_INIT_DESC, *PI2C_INIT_DESC; - wslaveaddr: 8bit Slave address - dwclockspeed: Input I2C clock spead(unit : Khz) - dwactualspeed: Output I2C clock spead(unit : Khz), the driver return actual setting value by this parameter IO Control Code I2C general read/write typedef struct _I2C_RW_DESC IOCTL_I2C_GENERAL_READ/ IOCTL_I2C_GENERAL_WRITE { PBYTE IO_pbtData; DWORD IN_dwData; BOOL IN_bStop; } I2C_READ_DESC, I2C_WRITE_DESC, *PI2C_READ_DESC, *PI2C_WRITE_DESC; - pbtdata: address of data buffer - dwdata: data count - bstop: Stop condition after operation is completed, if user wants make combination function then set this as FALSE 12
2 I2C DRIVER IO Control Code This IOCTL is used for slave which it operate slowly by itself typedef struct _I2C_SS_RW_DESC { IOCTL_I2C_SLOW_SLAVE_READ/ IOCTL_I2C_SLOW_SLAVE_WRITE PBYTE IO_pbtData; DWORD IN_dwData; DWORD IN_dwTime; BOOL IN_bStop; } I2C_SS_READ_DESC, I2C_SS_WRITE_DESC, *PI2C_SS_READ_DESC, *PI2C_SS_WRITE_DESC; - pbtdata: address of data buffer - dwdata: data count - dwtime: delay time after every ACK bit(unit : SCL clock) - bstop: Stop condition after operation is completed, if user wants make combination function then set this as FALSE IO Control Code IOCTL_I2C_CUSTOMX_READ/ IOCTL_I2C_CUSTOMX_WRITE Special function for customer use 2.6 Sample Code You can see the sample code in I2C_Sample.cpp 2.7 Debug Information [IIC_IST:E] SLAVE DETECTION IS FAILED It means that the slave is not connected to the master or slave address is invalid. 13
3 I2C EMULATION LIBRARY 3 I2C EMULATION LIBRARY 3.1 Introduction This emulation library is following I2C-BUS SPEC V2.1 This emulation library is tested with PMIC, AUDIO CODEC, CAMERA MODULE, ECHO CANCELLER, and IMAGE ENHANCEMENT. 3.2 Software Interface Table 3-1 Software Interface of the I2C Emulation Library Function I2C_EMUL_Init BYTE I2C_EMUL_Init(BYTE bgroup, PVOID pgpiobaseaddr, PVOID pbspargs, BYTE btslaveaddress, DWORD dwspeed) It initialize I2C emulator Parameter bgroup: Group Number(Group is a GPIO list that can be connected slaves) pgpiobaseaddr: accessible GPIO base address pbspargs: accessible BSP Argument address btslaveaddress: 7 bit slave address dwspeed: I2C bus spead(unit : Khz), this scale is not precise(+/- 20%) Return value zero mean success, otherwise fail Function I2C_EMUL_Write BYTE I2C_EMUL_Write(BYTE btgroup, BYTE bregaddr, BYTE bregdata ) Parameter btgroup: bus number which the slave is attached (refer to oal_i2cemul.h) bregaddr: register offset to write bregdata: data to write(just one byte) Return value zero mean success, otherwise fail 14
3 I2C EMULATION LIBRARY Function I2C_EMUL_Read BYTE I2C_EMUL_Read(BYTE btgroup, BYTE bregaddr, BYTE bregdata ) Parameter btgroup: bus number which the slave is attached (refer to oal_i2cemul.h) bregaddr: register offset to write bregdata: data to write(just one byte) Return value zero mean success, otherwise fail Function I2C_EMUL_MWrite BYTE I2C_EMUL_MWrite(BYTE btgroup, PBYTE pbtregdata, BYTE btwcount, BOOL bstop) It is combination function for writing. Parameter btgroup: bus number which the slave is attached (refer to oal_i2cemul.h) pbtregdata: (register offset, register data) array pointer or (register offset, register data list) pointer. It depend on a slave. btwcount: the size of pbtregdata bstop: if this flag is true, STOP condition will be sent in the end Return value zero mean success, otherwise fail Function I2C_EMUL_MRead BYTE I2C_EMUL_MRead(BYTE btgroup, PBYTE pbtregdata, BYTE btwcount, BOOL bstop) It is combination function for reading Parameter btgroup: bus number which the slave is attached (refer to oal_i2cemul.h) pbtregdata: (register offset, register data) array pointer or (register offset, register data list) pointer. It depend on a slave. btwcount: the size of pbtregdata bstop: if this flag is true, STOP condition will be sent in the end Return value zero mean success, otherwise fail 15
3 I2C EMULATION LIBRARY 3.3 Sample Code 3.3.1 Simple Function Following test example shows how to use simple function(pmic configuration) I2C_EMUL_Init(PMIC_GROUP,(PVOID) g_pgpioreg_wav, NULL, 0x66, 200); I2C_EMUL_Read(PMIC_GROUP, 0,&btOnOff); btonoff = (1<<2); I2C_EMUL_Write(PMIC_GROUP, 0, btonoff); I2C_EMUL_Read(PMIC_GROUP, 0,&btOnOff); It is recommended that user should use simple function if a slave is following I2C SPEC 3.3.2 Combination Function Following test example shows how to use combination function(example, Camera multi read) Read function of the camera module uses below format START+SLAVE_ADDR+REIGSER_OFFSET+REGISTER_DATA+ + (NOT STOP) + START + SLAVE_ADDR+REGISTER_DATA+ACK+ REGISTER_DATA+NAK+STOP I2C_EMUL_Init(CODEC_GROUP,(PVOID) g_pgpioreg_wav, NULL, slaveaddr, 200); brtn = I2C_EMUL_MWrite(CODEC_GROUP,(write_cmd_Buf, write_cnt, FALSE); if(!brtn) { brtn = I2C_EMUL_MRead(CODEC_GROUP,(Read_Buf, read_cnt, TRUE); } Combination function can cover all slaves. 3.4 Debug Information [I2CEMUL] VERSION INFO: XX This message is printed whenever you call I2CEMUL_Init function XX: Version number [I2CEMUL:ERROR] SLAVE IS HOLDING/[I2CEMUL:ERROR] BUS IS BUSY This message means that a slave is holding I2C bus or BUS is busy [I2CEMUL] SLAVE IS READY/[I2CEMUL] BUS IS READY This message means that slave release I2C BUS after slave holding I2C bus for a while, I2C BUS is not busy after a while 16