README (42300B)
1 This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 2 3 Copyright 2007-2019 Broadcom Inc. All rights reserved. 4 5 Broadcom StrataSwitch 6 I2C Device Driver API 7 8 Introduction 9 10 This document descrives the I2C bus-master driver for the CPU 11 Management Interface Controller (CMIC). This module provides common 12 I2C Bus driver routines for using the the I2C bus controller (internal 13 to the CMIC) as a bus-master. This is useful when using the I2C bus to 14 control auxiliary I2C slave devices connected to the SDA,SCL pins of a 15 StrataSwitch device. 16 17 Overview 18 19 The I2C Device Driver API allows for programming of I2C devices 20 connected to a Broadcom StrataSwitch through the CMIC I2C controller 21 (accessible via PCI). 22 23 The I2C bus is a 2-wire bus originally developed by Phillips 24 Semiconductor for bi-directional data I/O between two interconnected 25 integrated circuits (hence the name Inter-IC, IIC or I2C). The I2C bus 26 uses the 2-wires SDA (Serial Data) and SCL (Serial Clock) and each 27 device connected to the bus is addressable through a unique slave or 28 device address while simple master/slave relationships exist at all 29 times. Serial, 8-bit oriented, bi-directional data transfers can be 30 made at up to 400Kbits/sec in fast mode, with 100Kbits/s being the 31 norm. The number of IC's connected to this bus is limited only by a 32 maximum bus capacitance of 400pF. 33 34 35 Modules and Theory of Operation 36 37 A layering architecture is employed for the I2C drivers, this 38 layering and their source modules is described below. 39 40 +--------------------------------+ 41 | I2C read/write/ioctl API | src/bcm/bcmi2c.c 42 +--------------------------------+ 43 | I2C Device Drivers | src/drv/i2c/{lm75.c,max127.c,24c64.c} 44 +--------------------------------+ 45 | Server Management Bus Driver | src/drv/i2c/smbus.c 46 +---------------+----------------+ 47 | I2C Bus Driver| Device Manager | src/drv/i2c/{bus.c,devs.c} 48 +---------------+----------------+ 49 | PCI | src/drv/cmic.c 50 +---------------+ 51 52 The I2C driver is started by the system entry point soc_i2c_attach() 53 in bus.c which takes a PCI device number, flags, and an optional bus speed. 54 Both PIO and Interrupt driven modes of operation are supported. Speed, 55 if non-zero is used if a speed which is >= the provided speed can be found. 56 For most cases, the defaults for FLAGS and speed can be used. The attach 57 routine will initialize the bus-controller, and then attempt to perform 58 discovery by calling the probe routine (soc_i2c_probe). Note: This routine 59 can be invoked by typeing "i2c probe" from the BCM CLI. 60 61 The I2C device discovery entry point is soc_i2c_probe() in devs.c 62 which will iterate over every device in the I2C device table and attempt 63 to acknowledge-poll the device by generating START,SLAVE_ADDR and 64 waiting for an acknowledgment. When an acknowledgement is received, 65 the associated driver for the device is loaded. General call addresses 66 are NOT used and only devices added to the device descriptor table are 67 probed. 68 69 The core driver (bus.c) only deals with generating the bus conditions 70 and states required for I2C message processing. These routines are 71 low-level routines which assume that locking will occur at a 72 higher-level. For many devices, this will occur in the driver 73 definitions for a particular device or for those routines which use 74 the SMB protocol, locking is provided in the SMB module instead (smbus.c). 75 The file bus.c contains the core driver routines used for generating 76 START, STOP, REPSTART, and DATA conditions, along with state dependent 77 processing, and bus error handling. 78 79 I2C Devices which communicate via the SMB (Server Management Bus) 80 protocol can use the higher-level protocol operations defined in this 81 module (smbus.c). Note that support is provided for 8-bit and 16-bit 82 SMB r/w operations and all locking is provided in this module so every 83 module which uses it is MT-safe. For more advanced SMB features 84 (block read/write), see the implementation of the 24c64 EEPROM driver. 85 86 An I2C driver is used to communicate with an external slave device. I2C 87 drivers are used for every device which supports r/w operations. Devices 88 which use non-standard mechanisms for IO need only support the IO control 89 (ioctl) interface. The I2C device driver interface is defined in the 90 i2c_driver_t type, this driver is associated with the device type in 91 the i2c_device_t struct. For example drivers, see 24c64.c and lm75.c 92 93 When one or more drivers are added to the device driver association 94 table, devices are probed by the device layer (devs.c) which is responsible 95 for finding I2C devices, looking up a driver for a given slave address, 96 and associating a device with a driver callout. Users should implement their 97 driver, and then add the associated device entry to the i2c_devices[] 98 table in devs.c to make the device available to the system. 99 100 Finally, a high-level user API is provided for open/read/write/ioctl 101 style programming. Use of this API is dependent upon a driver for the 102 named device to be loaded into the system via the device probe layer. 103 This can be used to provide generic programmability of a wide variety 104 of devices while hiding the implementation details in the driver itself 105 and separating the device level interface from implementation. 106 107 In practice, a CLI or external management program will typically call 108 the API routines directly. See the file bcmi2c.c for more details, 109 also, see the CLI command implementation (diag/system/i2c_cmds.c) for 110 its use. 111 112 113 I2C Bus Driver API 114 115 The bus driver API (bus.c) allows for generating the bus conditions 116 and states required for I2C message processing. These routines are 117 low-level routines which assume that locking will occur at a 118 higher-level. In addition, they make various assumptions about 119 state-specific processing which will need to occur within higher level 120 routines. This documentation covers the general sequencing interface 121 which a higher-level driver will use to perform tasks such as I2C 122 attach, start, stop, read data, write data, detach, etc. It covers 123 user-serviceable routines only as internals are documented within 124 the source code. 125 126 Function: int soc_i2c_attach(int unit, int ena, uint32 flags, int speed) 127 Purpose: I2C Bus attach routine, main entry point for I2C startup. 128 Initialize the I2C controller configuration for the specified 129 device. Default is to disable the device, if ena is specified, 130 the default frequency is 100Khz. Flags currently allows 131 selection of Interrupt driven mode, PIO mode, or force 132 configuration. 133 Parameters: 134 135 unit - StrataSwitch device number or I2C bus number 136 enable - if non-zero, turn on and configure the bus 137 flags - bitmap (logical OR) of one or more of the following: 138 SOC_I2C_FORCE -force configuration 139 SOC_I2C_MODE_INTR - interrupt driven mode 140 SOC_I2C_MODE_PIO - programmed I/O mode 141 Returns: 142 143 SOC_E_NONE - operation succeeed, I2C bus ready for IO 144 SOC_E_MEMORY - memory allocation error 145 146 Notes: Default is Interrupt mode, if both are selected Interrupt is 147 chosen. 148 149 150 Function:int soc_i2c_start(int unit, uint8 slave_addr) 151 Purpose: Issue an I2C start command to the provided slave_addr. 152 For Transmit functions, the LSB should be cleared. 153 For Receive functions the LSB should be set. 154 Parameters: 155 unit - StrataSwitch device number or I2C bus number 156 slave_addr - I2C slave device address (LSB set for function). 157 158 Returns: SOC_E_NONE if the device was contacted and ready for I/O. 159 SOC_E_TIMEOUT if the device is not present. 160 161 If SOC_E_NONE is returned, you need to call soc_i2c_stop() 162 to release the bus when finished performing I/O. 163 164 See also: SOC_I2C_TX_ADDR(), SOC_I2C_RX_ADDR() 165 166 Notes: 10-bit addressing currently not supported. 167 168 169 Function: int soc_i2c_write_data(int unit, uint8 data) 170 Purpose: Write data to the last addressed slave device. 171 Parameters: 172 unit - StrataSwitch device number or I2C bus number 173 data - data byte to transmit 174 175 Returns: 176 SOC_E_NONE if the device was contacted and the operation 177 succeeded. 178 SOC_E_BUSY if the device timed out or is busy. 179 180 Notes: 181 Before this routine can be used, one must issue a START 182 condition on the bus along with the slave address used to 183 write to the device (e.g. a write address) 184 185 186 187 Function:int soc_i2c_read_data(int unit, uint8* data, int tx_ack) 188 Purpose: Read some data from the last addressed slave device. 189 190 Parameters: 191 192 unit - StrataSwitch device number or I2C bus number 193 data - address to place data byte received from slave 194 tx_ack - if set, an ACK will automatically be sent by the 195 controller when a slave sends data. If not set, 196 a NAK is pulsed when the byte has been received. 197 This is used for read operations where a master would 198 like to signify the last byte is being sent. 199 Returns: 200 201 SOC_E_NONE if the device was contacted and the operation 202 succeeded. 203 SOC_E_TIMEOUT if the device timed out. 204 Notes: 205 206 Before this routine can be used, one must issue a START 207 condition on the bus along with the slave address used to 208 read from the device (e.g. a write address). This means 209 for example, that bit0 must be set in the slave address. 210 We always transmit an ACK when tx_ack is non-zero. 211 212 213 Function: int soc_i2c_stop(int unit) 214 Purpose: Generate stop condition on the I2C bus. This routine is 215 used to signal the end of a data transfer and releases 216 the bus according to the I2C protocol. 217 218 Parameters: 219 unit - StrataSwitch device number or I2C bus number 220 221 Returns: 222 SOC_E_NONE - no error, one can always issue stop. 223 224 Notes: 225 none 226 227 Function: int soc_i2c_rep_start(int unit, uint8 slave_addr) 228 Purpose: Generate a repeated start to the specified slave address. 229 Typically, this is done in the middle of an operation in order 230 to delimit a new command sequence without releasing the I2C 231 bus. 232 233 Parameters: 234 unit - StrataSwitch device number or I2C bus number 235 slave_addr - device address, with r/w bit set for data direction. 236 237 Returns: 238 SOC_E_TIMEOUT - the device cannot be contacted or is offline 239 SOC_E_NONE - no error, device ready for IO. 240 241 Notes: 242 none 243 244 Function: int soc_i2c_ack_poll(int unit, uint8 io_addr, int maxpolls) 245 Purpose: Many devices will require a polling acknowledge cycle to 246 determine if the device is available for IO. Usually, this 247 means that a START condition is generated, along with a read 248 or write form of the slave device address, and then we wait 249 until the device responds with an ACK. When this occurs, we 250 issue a STOP, to free the bus, and return since the device 251 is ready for IO. 252 253 Parameters: 254 unit - StrataSwitch device number or I2C bus number 255 io_addr - device address, with r/w bit set for data direction. 256 max_polls - number of times to attempt the operation. 257 258 Returns: 259 Number of Poll operations required to contact device, or 260 maxpolls if the device is not online or responding. 261 262 Notes: Typically, we poll a specified IO address with the read/write bit 263 set to determine if the device is ready for reading or writing. 264 When we receive an ACK for that function (Read/Write), the device 265 is ready for IO. The data direction (or function) is determined 266 by the address bits (see SOC_I2C_TX_ADDR/SOC_I2C_RX_ADDR) macros. 267 268 Function: int soc_i2c_detach(int unit) 269 Purpose: I2C detach routine: free resources used by I2C bus driver. 270 Parameters: 271 unit - StrataSwitch device number or I2C bus number 272 273 Returns: 274 SOC_E_NONE - no error 275 276 Notes: 277 none 278 279 280 Function: soc_i2c_status_t soc_i2c_stat(int unit) 281 Purpose: Return bus status code in enumerated type format. 282 Parameters: 283 unit - StrataSwitch device number or I2C bus number 284 285 Returns: 286 bus status code as enumerated type definition 287 288 Notes: 289 This routine should be used in conjunction with 290 soc_i2c_status_message 291 292 293 Function:char* soc_i2c_status_message(soc_i2c_status_t status) 294 Purpose: This routine decodes the current I2C bus status code and 295 return human-readable bus status for last I2C operation 296 Returns: human readable character string telling what the 297 current status of the I2C bus is, NULL on invalid status code. 298 Notes: 299 See also: soc_i2c_stat (for getting current status value). 300 301 302 Server Management Bus (SMB) API Interface 303 304 The majority of I2C devices communicate using some form of SMB commands. 305 These commands consist of various protocol interactions between a host 306 chip and master I2C processor (the StrataSwitch family of switch chips). 307 308 Most devices use the SMBus (System Management Bus) protocol, which is 309 a subset of commands from the I2C protocol. Fortunately, many devices 310 use the same subset, which makes it possible to derive the following 311 SMBus operations/commands. 312 313 This module provides for SMB r/w byte and word commands based on 314 top of the bus driver module. Note that locking is performed in 315 this module, such that all drivers which use SMB commands are 316 automatically MT-safe. 317 318 When possible, please use the SMB commands for developing your I2C 319 device driver, as this will simplify debugging and development. 320 321 Below is a list of SMBus commands, all of the commands are based 322 on I2C protocol concepts. 323 324 Key to symbols 325 ============== 326 327 S (1 bit) : Start bit 328 P (1 bit) : Stop bit 329 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. 330 A, NA (1 bit) : Accept and reverse accept (ACK and Not ACK (NACK) ) bit. 331 Addr (7 bits): I2C 7 bit address. Note that this can be expanded 332 as usual to get a 10 bit I2C address. 333 Comm (8 bits): Command byte, a data byte which often selects a 334 register on the device. 335 Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh 336 for 16 bit data. 337 Count (8 bits): A data byte containing the length of a block operation. 338 339 [..]: Data sent by I2C device, as opposed to data sent by the host 340 adapter. 341 342 343 344 345 Function: int soc_i2c_read_byte(int unit, uint8 saddr, uint8* data) 346 347 Purpose: SMBus Read Quick/Byte 348 349 This Reads a single byte from the device 350 351 Algorithm: A Addr Rd [A] [Data] NA P 352 353 Parameters: 354 unit - StrataSwitch device number or I2C bus number 355 saddr - device base address, r bit should not be set. 356 data - 8 bit device-specific data value to read into. 357 358 Returns: 359 SOC_E_TIMEOUT - the device can not be contacted or is offline. 360 SOC_E_NONE - no error, operation succeeded. 361 362 Notes: 363 none 364 365 366 367 Function: int soc_i2c_write_byte(int unit, uint8 saddr, uint8 data) 368 369 Purpose: SMBus Write Quick/Byte 370 371 This sends a single byte to the device, at the place of the Rd/Wr bit. 372 There is no equivalent Read Quick command. 373 374 Algorithm: A Addr Rd/Wr [A] P 375 376 Parameters: 377 unit - StrataSwitch device number or I2C bus number 378 saddr - device base address, r bit should not be set. 379 data - 8 bit device-specific data value 380 381 Returns: 382 SOC_E_TIMEOUT - the device can not be contacted or is offline. 383 SOC_E_NONE - no error, operation succeeded. 384 385 Notes: 386 none 387 388 389 390 391 Function: int soc_i2c_read_word(int unit, uint8 saddr, uint16* value) 392 393 Purpose: SMBus Read Word 394 395 This reads a single word from the device. Some devices like to 396 perform split bus transaction; where a write byte command is 397 followed by a 16-bit read operation to fetch the last data 398 word from an action or state change which was performed by the 399 chip or device. 400 401 Algorithm: A Addr Rd [A] [Data] [A] [Data] NA P 402 403 Parameters: 404 unit - StrataSwitch device number or I2C bus number 405 saddr - device base address, r bit should not be set. 406 value - 16 bit device-specific data value to read. 407 408 Returns: 409 410 SOC_E_TIMEOUT - the device can not be contacted or is offline. 411 SOC_E_NONE - no error, operation succeeded. 412 413 Notes: 414 none 415 416 417 418 419 Function: int soc_i2c_write_word(int unit, uint8 saddr, uint16 value) 420 421 Purpose: SMBus Write Word 422 423 This command writes a single word to an I2C device. 424 425 Algorithm: S Addr Wr [A] DataHigh [A] DataLow [A] P 426 427 Parameters: 428 429 unit - StrataSwitch device number or I2C bus number 430 saddr - device base address, r bit should not be set. 431 value - 16 bit data value to write 432 433 Returns: 434 435 SOC_E_TIMEOUT - the device can not be contacted or is offline. 436 SOC_E_NONE - no error, operation succeeded. 437 438 Notes: 439 None 440 441 442 443 Function:int soc_i2c_read_byte_data(int unit, uint8 saddr, 444 uint8 com, uint8* value) 445 Purpose: SMBus read byte 446 447 This reads a single byte from a device, from a designated register. 448 The register is specified through the Comm byte. 449 450 Algorithm: S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P 451 452 Parameters: 453 454 unit - StrataSwitch device number or I2C bus number 455 saddr - device base address, r bit should not be set. 456 com - 8 bit device address or com port 457 value - address of where data byte should be stored 458 459 Returns: data byte in value parameter and one of the following: 460 461 SOC_E_TIMEOUT - the device can not be contacted or is offline. 462 SOC_E_NONE - no error, operation succeeded. 463 464 Notes: 465 none 466 467 468 469 Function: int soc_i2c_write_byte_data(int unit, uint8 saddr, 470 uint8 com, uint8 value) 471 Purpose: SMBus write byte 472 473 This writes a single byte to a device, to a designated register. The 474 register is specified through the Comm byte. This is the opposite of 475 the Read Byte Data command. 476 477 Algorithm: S Addr Wr [A] Comm [A] Data [A] P 478 479 Parameters: 480 481 unit - StrataSwitch device number or I2C bus number 482 saddr - device base address, r bit should not be set. 483 com - 8 bit device address or com port 484 value - data value to write 485 486 Returns: 487 488 SOC_E_TIMEOUT - the device can not be contacted or is offline. 489 SOC_E_NONE - no error, operation succeeded. 490 491 Notes: 492 none 493 494 495 496 Function:int soc_i2c_read_word_data(int unit, uint8 saddr, 497 uint8 com, uint16* value) 498 Purpose: SMBus Read Word Data 499 500 This command is very like Read Byte Data; again, data is read from a 501 device, from a designated register that is specified through the Comm 502 byte. But this time, the data is a complete word (16 bits). 503 504 Algorithm: 505 S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P 506 507 Parameters: 508 509 unit - StrataSwitch device number or I2C bus number 510 saddr - device base address, r bit should not be set. 511 com - 8 bit device address or com port 512 value - address where 16bit data value should be stored. 513 514 Returns: 16bit data value on success, and one of the following : 515 516 SOC_E_TIMEOUT - the device can not be contacted or is offline. 517 SOC_E_NONE - no error, operation succeeded. 518 519 Notes: 520 None 521 522 523 524 Function:int soc_i2c_write_word_data(int unit, uint8 saddr, 525 uint8 com, uint16 value) 526 527 Purpose: SMBus Write Word Data 528 529 This is the opposite operation of the Read Word Data command. 16 bits 530 of data is read from a device, from a designated register that is 531 specified through the Comm byte. 532 533 Algorithm: S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P 534 535 Parameters: 536 537 unit - StrataSwitch device number or I2C bus number 538 saddr - device base address, r bit should not be set. 539 com - 8 bit device address or com port 540 value - 16 bit data value to write 541 542 Returns: 543 544 SOC_E_TIMEOUT - the device can not be contacted or is offline. 545 SOC_E_NONE - no error, operation succeeded. 546 547 Notes: 548 None 549 550 551 552 Function: int soc_i2c_block_read(int unit, uint8 saddr, 553 uint8 com, uint8* count, uint8* data) 554 555 Purpose: SMBus Block Read 556 557 This command reads a block of upto 32 bytes from a device, from a 558 designated register that is specified through the Comm byte. The amount 559 of data is specified by the device in the Count byte. 560 561 Algorithm: S Addr Wr [A] Comm [A] 562 S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P 563 564 Parameters: 565 566 unit - StrataSwitch device number or I2C bus number 567 saddr - device base address, r bit should not be set. 568 com - 8 bit device address or com port 569 count - address where number of bytes read into data buff is stored. 570 data - address where data buffer should be stored. 571 572 Returns: 573 count - updated with the number of bytes successfullly read. 574 575 SOC_E_TIMEOUT - the device can not be contacted or is 576 offline, or the number of bytes specified 577 could not be read from the device. 578 579 SOC_E_NONE - no error, operation succeeded. 580 581 Notes: 582 None 583 584 585 586 Function: int soc_i2c_block_write(int unit, uint8 saddr, 587 uint8 com, uint8 count, uint8* data) 588 589 590 Purpose: SMBus Block Write 591 592 The opposite of the Block Read command, this writes upto 32 bytes to 593 a device, to a designated register that is specified through the 594 Comm byte. The amount of data is specified in the Count byte. 595 596 Algorithm: S Addr Wr [A] Comm [A] 597 Count [A] Data [A] Data [A] ... [A] Data [A] P 598 599 600 Parameters: 601 602 unit - StrataSwitch device number or I2C bus number 603 saddr - device base address, r bit should not be set. 604 com - 8 bit device address or com port 605 count - number of bytes to write from data buff. 606 data - address of data to write (data buffer). 607 608 Returns: 609 610 SOC_E_TIMEOUT - the device can not be contacted or is 611 offline, or the specified number of bytes 612 could not be written to the device. 613 614 SOC_E_NONE - no error, operation succeeded. 615 616 Notes: 617 None 618 619 620 I2C Device Driver Interface 621 622 I2C Device drivers are used by the system to identify a particular 623 device and provide for a high-level read/write or bulk data-transfer 624 capability. An I2C driver is a function vector with entry points for 625 initialization of the slave device, read, write, and ioctl operations. 626 627 628 629 typedef int (*i2c_read_func_t)(int unit, int devno, 630 uint16 addr, uint8* data, uint32* len); 631 typedef int (*i2c_write_func_t)(int unit, int devno, 632 uint16 addr, uint8* data, uint32 len); 633 typedef int (*i2c_ioc_func_t)(int unit, int devno, int opcode, 634 void* data, int len); 635 typedef int (*i2c_dev_init_func_t)(int unit, int devno, 636 void* data, int len); 637 /* 638 * I2C Driver structure: definitions for managed device operations. 639 */ 640 typedef struct i2c_driver_s{ 641 uint8 flags; /* Device flags */ 642 int devno; /* Index into device descriptor table */ 643 uint32 id; /* Device Serial No, or ID (unique)*/ 644 i2c_read_func_t read; /* Read routine */ 645 i2c_write_func_t write; /* Write routine */ 646 i2c_ioc_func_t ioctl; /* io control routine */ 647 i2c_dev_init_func_t load; /* called once at startup */ 648 } i2c_driver_t; 649 650 /* 651 * I2C Device Descriptor: One for every known device on the bus 652 */ 653 typedef struct i2c_dev_s{ 654 char devname[12]; /* Device name, eg. "eeprom0" */ 655 unsigned char saddr; /* Slave address */ 656 char desc[64]; /* Description */ 657 i2c_driver_t *driver;/* Driver routines */ 658 void* testdata; /* Test data */ 659 int testlen; /* Size of test data */ 660 uint32 tbyte; /* Bytes transmitted */ 661 uint32 rbyte; /* Bytes received */ 662 soc_i2c_bus_t *bus; /* Bus device attached to */ 663 } i2c_device_t; 664 665 666 Function: int soc_i2c_probe(int unit) 667 Purpose: Probe I2C devices on bus, report devices found. 668 This routine will walk through our internal I2C device driver 669 tables, attempt to find the device on the I2C bus, and if 670 successful, register a device driver for that device. 671 672 This allows for the device to be used in an API context as 673 when the devices are found, the device driver table is filled 674 with the correct entries for that device (r/w function, etc). 675 676 Parameters: 677 unit - StrataSwitch device number or I2C bus number 678 679 Return: 680 SOC_E_NONE - always returns with no errors. 681 682 683 684 Function:int soc_i2c_device_count(int unit) 685 Purpose: Report the number of devices registered 686 in the system. For now, this is the total number of devices 687 we have added to the statically defined device descriptor 688 array above. 689 690 Parameters: 691 unit - StrataSwitch device number or I2C bus number 692 693 Returns: 694 number of devices register in the system device table. 695 696 Notes: Currently, we do not support dynamic device loading. 697 Later, one will be able add a driver to the device table, 698 without the STATIC attribute. 699 700 701 Function: void soc_i2c_show(int unit) 702 Purpose: Show all valid devices and their attributes and 703 statistics. 704 Parameters: 705 unit - StrataSwitch device number or I2C bus number 706 Returns: 707 none 708 Notes: 709 none 710 711 712 Function: uint8 soc_i2c_addr(int unit, int devid) 713 Purpose: Return slave address of specified device. 714 Parameters: 715 unit - StrataSwitch device number or I2C bus number 716 devid - I2C device id returned from soc_i2c_devopen 717 718 Returns: 719 8-bit slave address of device 720 721 Notes: 722 none 723 724 725 Function: const char* soc_i2c_devname(int unit, int devid) 726 Purpose: Return device name of specified device. 727 Parameters: 728 unit - StrataSwitch device number or I2C bus number 729 devid - I2C device id returned from soc_i2c_devopen 730 731 Returns: 732 character string name of device 733 734 Notes: 735 none 736 737 738 Function: i2c_device_t* soc_i2c_device(int unit, int devid) 739 Purpose: Returns the device structure associated with the bus and 740 device identifier. 741 742 Parameters: 743 unit - StrataSwitch device number or I2C bus number 744 devid - I2C device id returned from soc_i2c_devopen 745 746 Returns: 747 I2C device descriptor 748 749 Notes: 750 none 751 752 753 Function: int soc_i2c_devtype(int unit, int devid) 754 Purpose: Return the device driver type, this is an integer value 755 associated with the driver to determine ownership of the 756 device. 757 758 Parameters: 759 unit - StrataSwitch device number or I2C bus number 760 devid - I2C device id returned from soc_i2c_devopen 761 762 Returns: 763 I2C device type code (from driver) 764 765 Notes: 766 Every device should have a unique Device type indentifier. 767 768 769 770 771 I2C Device Driver Registration 772 773 I2C devices are added to the I2C device driver table (i2c_devices), 774 along with their slave address, a string description, and their driver 775 (if available). 776 777 COMPILER_STATIC i2c_device_t 778 i2c_devices[] = { 779 {"nvram0", 0xa0, "Atmel 24C64 (64Kbit) Serial EEPROM #0", 780 &eep24c64_driver, eep24c64_test_data, eep24c64_test_data_len,0,0}, 781 {"nvram1", 0xa8, "Atmel 24C64 (64Kbit) Serial EEPROM #1", 782 &eep24c64_driver, eep24c64_test_data, eep24c64_test_data_len,0,0}, 783 {"lm75a", 0x90, "National LM75 Temperature Sensor A", 784 &lm75_driver, NULL, 0,0,0}, 785 {"lm75b", 0x98, "National LM75 Temperature Sensor B", 786 &lm75_driver, NULL, 0,0,0}, 787 {"adc0", 0x50, "Maxim MAX127 A/D Converter #0", 788 &max127_driver, NULL, 0,0,0}, 789 {"pll0", 0xd2, "Cypress W229B Clock Chip #0", 790 &w229b_driver, NULL, 0,0,0}, 791 }; 792 793 Add your device entry to this table, recompile, and attempt to probe for 794 your device. 795 796 797 I2C API Interface 798 799 Applications should attempt to separate interface from implementation 800 as much as possible and use the API calls to access their device; this 801 will allow vendor-specific I2C device drivers to work with newer versions 802 of the bus driver and I2C application framework. 803 804 Function: int bcm_i2c_open(int unit, char *devname, 805 uint32 flags, int speed) 806 807 Purpose: Open device, return valid file descriptor or -1 on error. 808 809 Parameters: 810 unit - StrataSwitch device number or I2C bus number 811 devname - I2C device name string 812 flags - arguments to pass to attach, default value should be zero 813 speed - I2C bus speed, if non-zero, this speed is configured, 814 normally this argument should be zero unless a speed 815 is desired. 816 Returns: 817 device identifier for all I2C operations 818 819 Notes: 820 This routine should be called before attempting to communicate 821 with an I2C device which has a registered driver. 822 A valid driver with this device name must be installed in the 823 system. 824 825 826 827 Function: int bcm_i2c_write(int unit, int fd, uint32 addr, 828 uint8 *data, uint32 nbytes) 829 Purpose: Write to a device 830 Parameters: 831 unit - StrataSwitch device number or I2C bus number 832 fd - I2C device ID 833 addr - device register or memory address 834 data - data byte buffer 835 nbytes - number of bytes of data 836 837 Returns: 838 Number of bytes written on success, -1 otherwise. 839 840 Notes: 841 This routine requires a driver. 842 843 844 845 846 Function: int bcm_i2c_read(int unit, int fd, 847 uint32 addr, uint8 *data, uint32nbytes) 848 Purpose: Read from a device 849 Parameters: 850 unit - StrataSwitch device number or I2C bus number 851 fd - I2C device ID 852 addr - device register or memory address 853 data - data byte buffer to read into 854 nbytes - number of bytes of data, updated on success. 855 856 Returns: 857 On success, number of bytes read; nbytes updated with number 858 of bytes read from device, -1 otherwise. 859 860 Notes: 861 This routine requires a driver. 862 863 864 Function: int bcm_i2c_ioctl(int unit, int fd, int opcode, 865 void *data, int len) 866 Purpose: Device specific I/O control 867 Parameters: 868 unit - StrataSwitch device number or I2C bus number 869 fd - I2C device ID 870 opcode - device command code (device-specific). 871 data - data byte buffer for command 872 nbytes - number of bytes of data 873 874 Returns: 875 On success, application specific value greater than zero, 876 -1 otherwise. 877 878 Notes: 879 This routine requires a driver. 880 881 882 Example I2C Driver: MAXIM MAX127 883 884 The MAX127 is a multi-range 12-bit D-A converter chip which provides 885 for eight (8) analog input channels that are independently software 886 programmable via I2C bus. On BCM956xx system boards, this device is 887 used to measure the voltages on the board. The device uses a split 888 transaction cycle where a bytes are written to the device and then a 889 word is read back for the A/D conversion cycle. A byte conversion 890 table for the operations is used to write to the device; each word 891 value read back is interpreted and displayed. 892 893 The initialization routine simply prints out that it found the device. 894 895 COMPILER_STATIC int 896 max127_init(int unit, int devno, 897 void* data, int len) 898 899 { 900 soc_cm_print("unit %d i2c 0x%x %s: MAX127 A/D Converter\n", 901 unit, soc_i2c_addr(unit, devno), 902 soc_i2c_devname(unit,devno)); 903 904 return SOC_E_NONE; 905 } 906 907 908 Since the A/D values are read-only, an ioctl style interface is chosen 909 for the driver, whereby it's invocation will print the output of the 910 A/D channels. Note that definition is static to preserve namespace 911 and the the transmit and receive stats are incremented after each 912 SMB transaction so that the "i2c show" command can report accurate stats 913 for this device. 914 915 COMPILER_STATIC int 916 max127_ioctl(int unit, int devno, 917 int opcode, void* data, int len) 918 { 919 int i; 920 uint16 val ; 921 uint8 saddr = soc_i2c_addr(unit, devno); 922 for(i = 0; i < N_MAX127_CHAN; i++){ 923 /* CHi start conversion, read back data */ 924 if(soc_i2c_write_byte(unit, saddr, max127_vals[i].cv) < 0){ 925 soc_cm_print("unit %d i2c %s: could not configure channel %d\n", 926 unit, soc_i2c_devname(unit,devno), i); 927 } 928 soc_i2c_device(unit, devno)->tbyte++; 929 930 /* Read back CHi conversion value */ 931 if(soc_i2c_read_word(unit, saddr, &val) < 0){ 932 soc_cm_print("unit %d i2c %s: could not read channel %d\n", 933 unit, soc_i2c_devname(unit,devno), i); 934 } 935 soc_i2c_device(unit, devno)->rbyte += 2; 936 937 soc_cm_print("\tCH%d=0x%2x/%.2f\n", 938 i, val, 939 max127_unipolar_value(val,max127_vals[i].r) ); 940 } 941 } 942 943 Define the MAX127 A-D converter driver callout. NOTE: both read and 944 write routines are stubs which return SOC_E_NONE when invocated. 945 946 i2c_driver_t max127_driver = { 947 0x0, 0x0, /* System assigned bytes */ 948 MAX127_DEVICE_TYPE, 949 max127_read, 950 max127_write, 951 max127_ioctl, 952 max127_init 953 }; 954 955 Add the device to the i2c_devices[] array in devs.c: 956 957 {"adc0", 0x50, "Maxim MAX127 A/D Converter #0", 958 &max127_driver, NULL, 0,0,0}, 959 960 961 In your program, open the device and perform ioctl operation. 962 963 if ( (fd = bcm_i2c_open(unit, "adc0",0,0)) < 0) { 964 printk("Could not open adc0: %s\n", bcm_errmsg(fd)); 965 return CMD_FAIL; 966 } 967 968 if ( (bcm_i2c_ioctl(unit, fd, 0, NULL, 0) < 0)) { 969 printk("Error: failed to perform A/D conversions.\n"); 970 } 971 972 In BCM, this command can be invoked from the CLI via the ADC 973 command: 974 975 BCM.0> adc show 976 CH0=0x55/3.32 977 CH1=0xc3/7.62 978 CH2=0xec/4.61 979 CH3=0x7f/2.48 980 CH4=0xf1/4.71 981 CH5=0x70/2.19 982 CH6=0xb2/3.48 983 CH7=0xbe/3.71 984 BCM.0> 985 986 987 988 BCM I2C Test Commands 989 990 A number of commands are provided in the file src/diag/i2c_cmds.c; 991 these commands allow for communication with I2C slave devices and 992 for configuration and testing of the I2C bus. These commands are 993 shown here for exemplary purposes: 994 995 996 997 BCM.0> i2c ? 998 Usages: 999 i2c probe [pio|intr] 1000 - probe devices on I2C bus and build device tree. 1001 If "intr" or "pio" is specified, use that bus mode. 1002 i2c retries [count] 1003 - set number of handshake attempts. 1004 i2c show 1005 - show devices found and their attributes. 1006 1007 The "i2c" command is used to probe the I2C bus, find all chips and 1008 load their drivers if available, and show devices and their statistics. 1009 It can also be used to change the I2C clock speed and I2C ack retry 1010 count for finicky devices. Note that speed is an undocumented setting 1011 at this point in time and when configured, the driver will emit M/N 1012 clock divider values. 1013 1014 BCM.0> i2c probe intr 75 1015 unit 0 i2c 0x60 bus: mode INTR, speed 67Kbps 1016 unit 0 i2c 0xa0 nvram0: 24C64 Serial EEPROM, 65524 bytes 1017 unit 0 i2c 0x50 adc0: MAX127 A/D Converter 1018 unit 0 i2c 0xd2 pll0: Cypress W229B/W311 Clock Chip 1019 BCM.0> adc show 1020 CH0=0x55/3.32 1021 CH1=0xc3/7.62 1022 CH2=0xec/4.61 1023 CH3=0x7f/2.48 1024 CH4=0xf1/4.71 1025 CH5=0x70/2.19 1026 CH6=0xb2/3.48 1027 CH7=0xbe/3.71 1028 BCM.0> 1029 1030 1031 1032 BCM.0> nvram ? 1033 Usages: 1034 nvram r [off] [nbytes] 1035 - show specified number of NVRAM bytes starting at offset. 1036 nvram w [off] [data] 1037 - write data byte to specified NVRAM offset. 1038 1039 The "nvram" command will use the BCM I2C API calls to open the device 1040 named "nvram" and allow reading and writing of bytes over I2C to the 1041 device. Note that the EEPROM driver will test all of NVRAM memory (64K) 1042 when it first sees the device and does not see a valid checksum in 1043 the first bytes of the NVRAM chip. 1044 1045 The 24C64 chip can be used to test the I2C bus, by writing a 0 value to 1046 the checksum offset of the NVRAM, and then re-attaching to the I2C bus 1047 with a specified speed until the device starts issuing too many retries 1048 and becomes unresponsive and essentially falls off the bus. 1049 1050 One can test the bus with the eeprom and a variety of speeds and limit 1051 the number of timeouts before we giveup on trying to talk to the 1052 device by setting the retries threshold. 1053 1054 1055 BCM.0> i2c ? 1056 Usages: 1057 i2c probe [pio|intr] 1058 - probe devices on I2C bus and build device tree. 1059 If "intr" or "pio" is specified, use that bus mode. 1060 i2c retries [count] 1061 - set number of handshake attempts. 1062 i2c show 1063 - show devices found and their attributes. 1064 1065 BCM.0> i2c retries 1066 BCM.0> nv w 1 0 1067 Using NVRAM device: nvram0 1068 BCM.0> i2c p p 1069 BCM5680_A0/i2c0: mode=PIO speed=100Kbps slave_addr=0x44 1070 NOTICE: EEPROM contents invalid or bad checksum. 1071 BCM5680_A0/i2c0/nvram0: 24C64 Serial EEPROM 1072 BCM5680_A0/i2c0/nvram0: testing data integrity data=0x178924,len=65536bytes 1073 Writing 65536 bytes [pattern=0x80] 1074 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, ACK Received] 1075 eep24c64_write(0,0,a200,128,24032): failed to gen start 1076 64KB write took 10.13 sec 6.31KB/sec 1077 EEPROM error: write failed: I2C device timed out 1078 Reading 65536 bytes ... 1079 64KB read took 6.72 sec 9.52KB/sec 1080 65536 bytes read OK 1081 EEPROM test passed (65536 bytes verified). 1082 BCM.0> i2c retries 5 1083 BCM.0> i2c p p 1084 BCM5680_A0/i2c0: mode=PIO speed=100Kbps slave_addr=0x44 1085 BCM5680_A0/i2c0/nvram0: 24C64 Serial EEPROM 65524 bytes cksum=0x71b7 1086 BCM.0> nv w 1 0 1087 Using NVRAM device: nvram0 1088 BCM.0> i2c p p 1089 BCM5680_A0/i2c0: mode=PIO speed=100Kbps slave_addr=0x44 1090 NOTICE: EEPROM contents invalid or bad checksum. 1091 BCM5680_A0/i2c0/nvram0: 24C64 Serial EEPROM 1092 BCM5680_A0/i2c0/nvram0: testing data integrity data=0x178924,len=65536bytes 1093 Writing 65536 bytes [pattern=0x0] 1094 64KB write took 16.01 sec 4.00KB/sec 1095 65536 bytes written OK 1096 Reading 65536 bytes ... 1097 64KB read took 6.72 sec 9.52KB/sec 1098 65536 bytes read OK 1099 EEPROM test passed (65536 bytes verified). 1100 BCM.0> nv w 1 0 1101 Using NVRAM device: nvram0 1102 BCM.0> i2c p p 150 1103 soc_i2c_set_freq: i2c0 speed=150.00KHz (153600) 1104 soc_i2c_set_freq: i2c0: just set M=8 N=0: 138.89KHz 1105 BCM5680_A0/i2c0: mode=PIO speed=150Kbps slave_addr=0x44 1106 BCM.0> nv w 1 0 1107 Using NVRAM device: nvram0 1108 eep24c64_write(0,0,1,0,-30): failed to gen start 1109 Error: write of byte at 0x1 failed:I2C device timed out 1110 BCM.0> i2c p p 150 1111 soc_i2c_set_freq: i2c0 speed=150.00KHz (153600) 1112 soc_i2c_set_freq: i2c0: just set M=8 N=0: 138.89KHz 1113 BCM5680_A0/i2c0: mode=PIO speed=150Kbps slave_addr=0x44 1114 BCM.0> nv w 1 0 1115 Using NVRAM device: nvram0 1116 eep24c64_write(0,0,1,0,-30): failed to gen start 1117 Error: write of byte at 0x1 failed:I2C device timed out 1118 BCM.0> i2c p p 100 1119 soc_i2c_set_freq: i2c0 speed=100.00KHz (102400) 1120 soc_i2c_set_freq: i2c0: just set M=12 N=0: 96.15KHz 1121 BCM5680_A0/i2c0: mode=PIO speed=100Kbps slave_addr=0x44 1122 NOTICE: EEPROM contents invalid or bad checksum. 1123 BCM5680_A0/i2c0/nvram0: 24C64 Serial EEPROM 1124 BCM5680_A0/i2c0/nvram0: testing data integrity data=0x178924,len=65536bytes 1125 Writing 65536 bytes [pattern=0x80] 1126 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1127 64KB write took 18.38 sec 3.48KB/sec 1128 65536 bytes written OK 1129 Reading 65536 bytes ... 1130 64KB read took 8.64 sec 7.40KB/sec 1131 65536 bytes read OK 1132 EEPROM test passed (65536 bytes verified). 1133 BCM.0> i2c 1134 BCM5680_A0/i2c0/nvram0 @0xa0 [Atmel 24C64 (64Kbit) Serial EEPROM #0] 1135 nvram0: driver attached 1136 172684 bytes transmitted 1137 196668 bytes received 1138 Read@0x17ec74 1139 Write@0x17ec78 1140 Ioctl@0x17ec7c 1141 Load@0x17ec80 1142 BCM.0> i2c retries 100 1143 BCM.0> i2c p p 2000 1144 soc_i2c_set_freq: i2c0 speed=1.95MHz (2048000) 1145 soc_i2c_set_freq: i2c0: just set M=0 N=0: 1.25MHz 1146 BCM5680_A0/i2c0: mode=PIO speed=2000Kbps slave_addr=0x44 1147 BCM.0> nv w 0 1 1148 Using NVRAM device: nvram0 1149 eep24c64_write(0,0,0,1,1): failed to gen start 1150 Error: write of byte at 0x0 failed:I2C device timed out 1151 BCM.0> i2c p p 120 1152 soc_i2c_set_freq: i2c0 speed=120.00KHz (122880) 1153 soc_i2c_set_freq: i2c0: just set M=10 N=0: 113.64KHz 1154 BCM5680_A0/i2c0: mode=PIO speed=120Kbps slave_addr=0x44 1155 BCM5680_A0/i2c0/nvram0: 24C64 Serial EEPROM 65524 bytes cksum=0x71b7 1156 BCM.0> nv w 0 1 1157 Using NVRAM device: nvram0 1158 BCM.0> i2c p p 120 1159 soc_i2c_set_freq: i2c0 speed=120.00KHz (122880) 1160 soc_i2c_set_freq: i2c0: just set M=10 N=0: 113.64KHz 1161 BCM5680_A0/i2c0: mode=PIO speed=120Kbps slave_addr=0x44 1162 NOTICE: EEPROM contents invalid or bad checksum. 1163 BCM5680_A0/i2c0/nvram0: 24C64 Serial EEPROM 1164 BCM5680_A0/i2c0/nvram0: testing data integrity data=0x178924,len=65536bytes 1165 Writing 65536 bytes [pattern=0x0] 1166 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1167 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1168 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1169 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1170 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1171 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1172 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1173 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1174 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, ACK Received] 1175 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1176 BCM5680_A0/i2c0:STATUS:[Data Byte Transmitted, NO ACK Received] 1177 64KB write took 11.52 sec 5.55KB/sec 1178 65536 bytes written OK 1179 Reading 65536 bytes ... 1180 64KB read took 2.87 sec 22.30KB/sec 1181 65536 bytes read OK 1182 EEPROM test passed (65536 bytes verified). 1183 BCM.0> 1184 1185 From the data above, it looks like 120Khz is the fastest setting we 1186 can use with MPC8240 and the 24C64 in PIO mode. Note that since the 1187 driver is performing a lot of retries at this speed, 100Khz is probably 1188 optimal. Similar strategies can be employeed for debugging and tuning 1189 other devices. 1190 1191 1192 Known Issues 1193 1194 This driver supports master-mode only at this time. Currently, slave 1195 mode is supported only in HW. 1196 1197 When soc_i2c_attach is invoked, the bus driver programs every PCI 1198 chip with a new slave address based on the algorithm: addr = 0x60 (Default) * 1199 pci_devid * 4, hence each I2C bus will have a unique slave address at 1200 a multiple of 4, and multiple PCI bus-controller chips is possible in 1201 multi-switch systems. 1202 1203 Note: The I2C controller will automatically enter slave transmit mode 1204 if it receives it's own Slave address with the read bit set. 1205 Similarly, the I2C controller will automatically enter slave receive 1206 mode if it receives it's own slave address and the write bit, or the 1207 general call address. The implication is that, at the time of this 1208 writing, you cannot have two masters with the same slave address or 1209 use the General call address while one of the chips is an I2C master. 1210 1211 References 1212 1213 * StrataSwitch Register Reference (BCM56xx), Broadcom Corporation 1214 http:/www.broadcom.com/ 1215 * The I2C Bus Specification : Version 2.1, Phillips Semiconductor 1216 http://www.semiconductors.philips.com/i2c/ 1217 * LM75 Databook, National Semiconductor 1218 http://www.national.com/ 1219 * 24C64 64K I2C EEPROM Data Sheet, Atmel Corporation 1220 http://www.atmel.com/ 1221 * MAX127 A/D Converter, Dallas/MAXIM Semiconductor 1222 http://www.maxim-ic.com/ 1223 * W229b Clock Generator Databook, Cypress Semiconductor 1224 http://www.cypress.com/