1ccf988b6SMauro Carvalho Chehab===================== 2ccf988b6SMauro Carvalho ChehabI2C/SMBUS Fault Codes 3ccf988b6SMauro Carvalho Chehab===================== 4ccf988b6SMauro Carvalho Chehab 5ccf988b6SMauro Carvalho ChehabThis is a summary of the most important conventions for use of fault 6ccf988b6SMauro Carvalho Chehabcodes in the I2C/SMBus stack. 7ccf988b6SMauro Carvalho Chehab 8ccf988b6SMauro Carvalho Chehab 9ccf988b6SMauro Carvalho ChehabA "Fault" is not always an "Error" 10ccf988b6SMauro Carvalho Chehab---------------------------------- 11ccf988b6SMauro Carvalho ChehabNot all fault reports imply errors; "page faults" should be a familiar 12ccf988b6SMauro Carvalho Chehabexample. Software often retries idempotent operations after transient 13ccf988b6SMauro Carvalho Chehabfaults. There may be fancier recovery schemes that are appropriate in 14ccf988b6SMauro Carvalho Chehabsome cases, such as re-initializing (and maybe resetting). After such 15ccf988b6SMauro Carvalho Chehabrecovery, triggered by a fault report, there is no error. 16ccf988b6SMauro Carvalho Chehab 17ccf988b6SMauro Carvalho ChehabIn a similar way, sometimes a "fault" code just reports one defined 18ccf988b6SMauro Carvalho Chehabresult for an operation ... it doesn't indicate that anything is wrong 19ccf988b6SMauro Carvalho Chehabat all, just that the outcome wasn't on the "golden path". 20ccf988b6SMauro Carvalho Chehab 21ccf988b6SMauro Carvalho ChehabIn short, your I2C driver code may need to know these codes in order 22ccf988b6SMauro Carvalho Chehabto respond correctly. Other code may need to rely on YOUR code reporting 23ccf988b6SMauro Carvalho Chehabthe right fault code, so that it can (in turn) behave correctly. 24ccf988b6SMauro Carvalho Chehab 25ccf988b6SMauro Carvalho Chehab 26ccf988b6SMauro Carvalho ChehabI2C and SMBus fault codes 27ccf988b6SMauro Carvalho Chehab------------------------- 28ccf988b6SMauro Carvalho ChehabThese are returned as negative numbers from most calls, with zero or 29ccf988b6SMauro Carvalho Chehabsome positive number indicating a non-fault return. The specific 30ccf988b6SMauro Carvalho Chehabnumbers associated with these symbols differ between architectures, 31ccf988b6SMauro Carvalho Chehabthough most Linux systems use <asm-generic/errno*.h> numbering. 32ccf988b6SMauro Carvalho Chehab 33ccf988b6SMauro Carvalho ChehabNote that the descriptions here are not exhaustive. There are other 34ccf988b6SMauro Carvalho Chehabcodes that may be returned, and other cases where these codes should 35ccf988b6SMauro Carvalho Chehabbe returned. However, drivers should not return other codes for these 36ccf988b6SMauro Carvalho Chehabcases (unless the hardware doesn't provide unique fault reports). 37ccf988b6SMauro Carvalho Chehab 38ccf988b6SMauro Carvalho ChehabAlso, codes returned by adapter probe methods follow rules which are 39ccf988b6SMauro Carvalho Chehabspecific to their host bus (such as PCI, or the platform bus). 40ccf988b6SMauro Carvalho Chehab 41ccf988b6SMauro Carvalho Chehab 42ccf988b6SMauro Carvalho ChehabEAGAIN 43ccf988b6SMauro Carvalho Chehab Returned by I2C adapters when they lose arbitration in master 44ccf988b6SMauro Carvalho Chehab transmit mode: some other master was transmitting different 45ccf988b6SMauro Carvalho Chehab data at the same time. 46ccf988b6SMauro Carvalho Chehab 47ccf988b6SMauro Carvalho Chehab Also returned when trying to invoke an I2C operation in an 48ccf988b6SMauro Carvalho Chehab atomic context, when some task is already using that I2C bus 49ccf988b6SMauro Carvalho Chehab to execute some other operation. 50ccf988b6SMauro Carvalho Chehab 51ccf988b6SMauro Carvalho ChehabEBADMSG 52ccf988b6SMauro Carvalho Chehab Returned by SMBus logic when an invalid Packet Error Code byte 53ccf988b6SMauro Carvalho Chehab is received. This code is a CRC covering all bytes in the 54ccf988b6SMauro Carvalho Chehab transaction, and is sent before the terminating STOP. This 55ccf988b6SMauro Carvalho Chehab fault is only reported on read transactions; the SMBus slave 56ccf988b6SMauro Carvalho Chehab may have a way to report PEC mismatches on writes from the 57ccf988b6SMauro Carvalho Chehab host. Note that even if PECs are in use, you should not rely 58ccf988b6SMauro Carvalho Chehab on these as the only way to detect incorrect data transfers. 59ccf988b6SMauro Carvalho Chehab 60ccf988b6SMauro Carvalho ChehabEBUSY 61ccf988b6SMauro Carvalho Chehab Returned by SMBus adapters when the bus was busy for longer 62ccf988b6SMauro Carvalho Chehab than allowed. This usually indicates some device (maybe the 63ccf988b6SMauro Carvalho Chehab SMBus adapter) needs some fault recovery (such as resetting), 64ccf988b6SMauro Carvalho Chehab or that the reset was attempted but failed. 65ccf988b6SMauro Carvalho Chehab 66ccf988b6SMauro Carvalho ChehabEINVAL 67ccf988b6SMauro Carvalho Chehab This rather vague error means an invalid parameter has been 68ccf988b6SMauro Carvalho Chehab detected before any I/O operation was started. Use a more 69ccf988b6SMauro Carvalho Chehab specific fault code when you can. 70ccf988b6SMauro Carvalho Chehab 71ccf988b6SMauro Carvalho ChehabEIO 72ccf988b6SMauro Carvalho Chehab This rather vague error means something went wrong when 73ccf988b6SMauro Carvalho Chehab performing an I/O operation. Use a more specific fault 74ccf988b6SMauro Carvalho Chehab code when you can. 75ccf988b6SMauro Carvalho Chehab 76ccf988b6SMauro Carvalho ChehabENODEV 77ccf988b6SMauro Carvalho Chehab Returned by driver probe() methods. This is a bit more 78ccf988b6SMauro Carvalho Chehab specific than ENXIO, implying the problem isn't with the 79ccf988b6SMauro Carvalho Chehab address, but with the device found there. Driver probes 80ccf988b6SMauro Carvalho Chehab may verify the device returns *correct* responses, and 81ccf988b6SMauro Carvalho Chehab return this as appropriate. (The driver core will warn 82ccf988b6SMauro Carvalho Chehab about probe faults other than ENXIO and ENODEV.) 83ccf988b6SMauro Carvalho Chehab 84ccf988b6SMauro Carvalho ChehabENOMEM 85ccf988b6SMauro Carvalho Chehab Returned by any component that can't allocate memory when 86ccf988b6SMauro Carvalho Chehab it needs to do so. 87ccf988b6SMauro Carvalho Chehab 88ccf988b6SMauro Carvalho ChehabENXIO 89ccf988b6SMauro Carvalho Chehab Returned by I2C adapters to indicate that the address phase 90ccf988b6SMauro Carvalho Chehab of a transfer didn't get an ACK. While it might just mean 91ccf988b6SMauro Carvalho Chehab an I2C device was temporarily not responding, usually it 92ccf988b6SMauro Carvalho Chehab means there's nothing listening at that address. 93ccf988b6SMauro Carvalho Chehab 94ccf988b6SMauro Carvalho Chehab Returned by driver probe() methods to indicate that they 95ccf988b6SMauro Carvalho Chehab found no device to bind to. (ENODEV may also be used.) 96ccf988b6SMauro Carvalho Chehab 97ccf988b6SMauro Carvalho ChehabEOPNOTSUPP 98ccf988b6SMauro Carvalho Chehab Returned by an adapter when asked to perform an operation 99ccf988b6SMauro Carvalho Chehab that it doesn't, or can't, support. 100ccf988b6SMauro Carvalho Chehab 101ccf988b6SMauro Carvalho Chehab For example, this would be returned when an adapter that 102ccf988b6SMauro Carvalho Chehab doesn't support SMBus block transfers is asked to execute 103ccf988b6SMauro Carvalho Chehab one. In that case, the driver making that request should 104ccf988b6SMauro Carvalho Chehab have verified that functionality was supported before it 105ccf988b6SMauro Carvalho Chehab made that block transfer request. 106ccf988b6SMauro Carvalho Chehab 107ccf988b6SMauro Carvalho Chehab Similarly, if an I2C adapter can't execute all legal I2C 108ccf988b6SMauro Carvalho Chehab messages, it should return this when asked to perform a 109ccf988b6SMauro Carvalho Chehab transaction it can't. (These limitations can't be seen in 110ccf988b6SMauro Carvalho Chehab the adapter's functionality mask, since the assumption is 111ccf988b6SMauro Carvalho Chehab that if an adapter supports I2C it supports all of I2C.) 112ccf988b6SMauro Carvalho Chehab 113ccf988b6SMauro Carvalho ChehabEPROTO 114ccf988b6SMauro Carvalho Chehab Returned when slave does not conform to the relevant I2C 115ccf988b6SMauro Carvalho Chehab or SMBus (or chip-specific) protocol specifications. One 116ccf988b6SMauro Carvalho Chehab case is when the length of an SMBus block data response 117ccf988b6SMauro Carvalho Chehab (from the SMBus slave) is outside the range 1-32 bytes. 118ccf988b6SMauro Carvalho Chehab 119ccf988b6SMauro Carvalho ChehabESHUTDOWN 120ccf988b6SMauro Carvalho Chehab Returned when a transfer was requested using an adapter 121ccf988b6SMauro Carvalho Chehab which is already suspended. 122ccf988b6SMauro Carvalho Chehab 123ccf988b6SMauro Carvalho ChehabETIMEDOUT 124ccf988b6SMauro Carvalho Chehab This is returned by drivers when an operation took too much 125ccf988b6SMauro Carvalho Chehab time, and was aborted before it completed. 126ccf988b6SMauro Carvalho Chehab 127ccf988b6SMauro Carvalho Chehab SMBus adapters may return it when an operation took more 128ccf988b6SMauro Carvalho Chehab time than allowed by the SMBus specification; for example, 129ccf988b6SMauro Carvalho Chehab when a slave stretches clocks too far. I2C has no such 130ccf988b6SMauro Carvalho Chehab timeouts, but it's normal for I2C adapters to impose some 131ccf988b6SMauro Carvalho Chehab arbitrary limits (much longer than SMBus!) too. 132