I2C/SMBUS Fault Codes

fault가 항상 error는 아님

이 문서는 I2C/SMBus 스택에서 fault code를 사용하는 가장 중요한 관례를 요약합니다.

모든 fault 보고가 error를 뜻하지는 않습니다. page fault가 익숙한 예입니다. 소프트웨어는 일시적인 fault 뒤에 멱등 연산을 재시도하곤 합니다. 경우에 따라 재초기화나 reset 같은 더 정교한 복구가 적절하며, fault 보고로 복구한 뒤에는 error가 남지 않습니다.

마찬가지로 fault code가 연산의 정의된 결과 하나를 보고할 뿐인 때도 있습니다. 잘못된 것이 아니라 결과가 정상 경로와 달랐다는 뜻입니다.

따라서 I2C 드라이버 코드는 올바르게 대응하려면 이 코드를 알아야 합니다. 다른 코드도 올바르게 동작하려고 드라이버가 정확한 fault code를 보고하는 것에 의존할 수 있습니다.

=====================
I2C/SMBUS Fault Codes
=====================

This is a summary of the most important conventions for use of fault
codes in the I2C/SMBus stack.


A "Fault" is not always an "Error"
----------------------------------
Not all fault reports imply errors; "page faults" should be a familiar
example.  Software often retries idempotent operations after transient
faults.  There may be fancier recovery schemes that are appropriate in
some cases, such as re-initializing (and maybe resetting).  After such
recovery, triggered by a fault report, there is no error.

In a similar way, sometimes a "fault" code just reports one defined
result for an operation ... it doesn't indicate that anything is wrong
at all, just that the outcome wasn't on the "golden path".

In short, your I2C driver code may need to know these codes in order
to respond correctly.  Other code may need to rely on YOUR code reporting
the right fault code, so that it can (in turn) behave correctly.

I2C·SMBus 반환값 관례

대부분의 호출은 fault를 음수로 반환하며 0 또는 양수는 fault가 아님을 나타냅니다. 기호에 대응하는 실제 숫자는 아키텍처마다 다르지만 대부분의 Linux 시스템은 `<asm-generic/errno*.h>` 번호를 사용합니다.

여기 설명은 완전한 목록이 아닙니다. 다른 코드가 반환될 수도 있고 같은 코드가 필요한 다른 사례도 있습니다. 그러나 하드웨어가 fault를 구별해 보고하지 못하는 경우를 제외하면, 아래 사례에 드라이버가 다른 코드를 반환해서는 안 됩니다.

어댑터 `probe` 메서드가 반환하는 코드는 PCI나 platform bus 같은 호스트 버스별 규칙도 따릅니다.

I2C and SMBus fault codes
-------------------------
These are returned as negative numbers from most calls, with zero or
some positive number indicating a non-fault return.  The specific
numbers associated with these symbols differ between architectures,
though most Linux systems use <asm-generic/errno*.h> numbering.

Note that the descriptions here are not exhaustive.  There are other
codes that may be returned, and other cases where these codes should
be returned.  However, drivers should not return other codes for these
cases (unless the hardware doesn't provide unique fault reports).

Also, codes returned by adapter probe methods follow rules which are
specific to their host bus (such as PCI, or the platform bus).

주소·중재·PEC·버스 점유 fault

`EAFNOSUPPORT`는 10비트 주소를 지원하지 않는 I2C 어댑터에 10비트 주소 사용을 요청했을 때 반환합니다.

`EAGAIN`은 마스터 송신 중 중재를 잃었을 때 반환합니다. 다른 마스터가 동시에 다른 데이터를 전송한 경우입니다. atomic context에서 I2C 연산을 호출하려는데 다른 task가 이미 그 버스를 사용하는 경우에도 반환합니다.

`EBADMSG`는 SMBus 로직이 잘못된 Packet Error Code 바이트를 받았을 때 반환합니다. PEC는 트랜잭션의 모든 바이트를 덮는 CRC이며 마지막 STOP 전에 전송됩니다. 이 fault는 읽기에서만 보고되고, 쓰기의 PEC 불일치는 슬레이브가 별도 방식으로 호스트에 알릴 수 있습니다. PEC를 사용해도 잘못된 데이터 전송을 감지하는 유일한 수단으로 의존해서는 안 됩니다.

`EBUSY`는 버스가 허용 시간보다 오래 busy였을 때 SMBus 어댑터가 반환합니다. 보통 어떤 장치나 어댑터에 reset 같은 fault 복구가 필요하거나, reset을 시도했지만 실패했음을 나타냅니다.

EAFNOSUPPORT
        Returned by I2C adapters not supporting 10 bit addresses when
        they are requested to use such an address.

EAGAIN
        Returned by I2C adapters when they lose arbitration in master
        transmit mode:  some other master was transmitting different
        data at the same time.

        Also returned when trying to invoke an I2C operation in an
        atomic context, when some task is already using that I2C bus
        to execute some other operation.

EBADMSG
        Returned by SMBus logic when an invalid Packet Error Code byte
        is received.  This code is a CRC covering all bytes in the
        transaction, and is sent before the terminating STOP.  This
        fault is only reported on read transactions; the SMBus slave
        may have a way to report PEC mismatches on writes from the
        host.  Note that even if PECs are in use, you should not rely
        on these as the only way to detect incorrect data transfers.

EBUSY
        Returned by SMBus adapters when the bus was busy for longer
        than allowed.  This usually indicates some device (maybe the
        SMBus adapter) needs some fault recovery (such as resetting),
        or that the reset was attempted but failed.

일반 I/O·장치·주소 fault

`EINVAL`은 I/O를 시작하기 전에 잘못된 매개변수를 감지했다는 다소 모호한 오류입니다. 가능하면 더 구체적인 fault code를 사용하십시오.

`EIO`는 I/O 연산 수행 중 무언가 잘못되었다는 다소 모호한 오류입니다. 가능하면 더 구체적인 fault code를 사용하십시오.

`ENODEV`는 드라이버 `probe()`가 반환합니다. 주소 문제가 아니라 그 주소에서 찾은 장치가 문제라는 점에서 `ENXIO`보다 구체적입니다. probe는 장치가 올바른 응답을 반환하는지 검증한 뒤 적절히 이 코드를 반환할 수 있습니다. 드라이버 core는 `ENXIO`와 `ENODEV` 이외의 probe fault를 경고합니다.

`ENOMEM`은 필요한 메모리를 할당할 수 없는 구성 요소가 반환합니다.

`ENXIO`는 전송 주소 단계가 ACK를 받지 못했음을 I2C 어댑터가 나타낼 때 반환합니다. 장치가 일시적으로 응답하지 않는 경우도 있지만 보통 해당 주소에 수신 장치가 없다는 뜻입니다.

드라이버 `probe()`가 결합할 장치를 찾지 못했음을 나타낼 때도 `ENXIO`를 반환합니다. 이때 `ENODEV`도 사용할 수 있습니다.

EINVAL
        This rather vague error means an invalid parameter has been
        detected before any I/O operation was started.  Use a more
        specific fault code when you can.

EIO
        This rather vague error means something went wrong when
        performing an I/O operation.  Use a more specific fault
        code when you can.

ENODEV
        Returned by driver probe() methods.  This is a bit more
        specific than ENXIO, implying the problem isn't with the
        address, but with the device found there.  Driver probes
        may verify the device returns *correct* responses, and
        return this as appropriate.  (The driver core will warn
        about probe faults other than ENXIO and ENODEV.)

ENOMEM
        Returned by any component that can't allocate memory when
        it needs to do so.

ENXIO
        Returned by I2C adapters to indicate that the address phase
        of a transfer didn't get an ACK.  While it might just mean
        an I2C device was temporarily not responding, usually it
        means there's nothing listening at that address.

        Returned by driver probe() methods to indicate that they
        found no device to bind to.  (ENODEV may also be used.)

미지원·프로토콜·중지·시간 초과

`EOPNOTSUPP`는 어댑터가 지원하지 않거나 수행할 수 없는 연산을 요청받았을 때 반환합니다. 예를 들어 SMBus block transfer를 지원하지 않는 어댑터에 이를 요청하면 반환합니다. 요청 드라이버는 block transfer 전에 기능 지원을 확인했어야 합니다.

마찬가지로 I2C 어댑터가 합법적인 모든 I2C 메시지를 실행할 수 없다면 수행 불가능한 트랜잭션 요청에 이 코드를 반환해야 합니다. 어댑터가 I2C를 지원하면 전체 I2C를 지원한다고 가정하므로 이런 제한은 functionality mask에 나타낼 수 없습니다.

`EPROTO`는 슬레이브가 관련 I2C, SMBus 또는 칩 고유 프로토콜 규격을 따르지 않을 때 반환합니다. 예를 들어 SMBus 슬레이브의 block data 응답 길이가 1~32바이트 범위를 벗어난 경우입니다.

`ESHUTDOWN`은 이미 suspend된 어댑터로 전송을 요청했을 때 반환합니다.

`ETIMEDOUT`은 연산이 너무 오래 걸려 완료 전에 중단했을 때 드라이버가 반환합니다. SMBus 어댑터는 슬레이브가 클록을 지나치게 늘이는 등 SMBus 규격의 허용 시간을 넘으면 반환할 수 있습니다. I2C에는 그런 timeout이 없지만 I2C 어댑터가 SMBus보다 훨씬 긴 임의 제한을 두는 것은 일반적입니다.

EOPNOTSUPP
        Returned by an adapter when asked to perform an operation
        that it doesn't, or can't, support.

        For example, this would be returned when an adapter that
        doesn't support SMBus block transfers is asked to execute
        one.  In that case, the driver making that request should
        have verified that functionality was supported before it
        made that block transfer request.

        Similarly, if an I2C adapter can't execute all legal I2C
        messages, it should return this when asked to perform a
        transaction it can't.  (These limitations can't be seen in
        the adapter's functionality mask, since the assumption is
        that if an adapter supports I2C it supports all of I2C.)

EPROTO
        Returned when slave does not conform to the relevant I2C
        or SMBus (or chip-specific) protocol specifications.  One
        case is when the length of an SMBus block data response
        (from the SMBus slave) is outside the range 1-32 bytes.

ESHUTDOWN
        Returned when a transfer was requested using an adapter
        which is already suspended.

ETIMEDOUT
        This is returned by drivers when an operation took too much
        time, and was aborted before it completed.

        SMBus adapters may return it when an operation took more
        time than allowed by the SMBus specification; for example,
        when a slave stretches clocks too far.  I2C has no such
        timeouts, but it's normal for I2C adapters to impose some
        arbitrary limits (much longer than SMBus!) too.