// Copyright 2021 the u-root Authors. All rights reserved // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. // Package spidev wraps the Linux spidev driver and performs low-level SPI // operations. package spidev import ( "bytes" "encoding/binary" "fmt" "io" "math" "os" "runtime" "unsafe" "golang.org/x/sys/unix" ) // See Linux "include/uapi/linux/spi/spidev.h" and // "Documentation/spi/spidev.rst" // Various ioctl numbers. const ( iocRdMode = 0x80016b01 iocWrMode = 0x40016b01 iocRdLSBFirst = 0x80016b02 iocWrLSBFirst = 0x40016b02 iocRdBitsPerWord = 0x80016b03 iocWrBitsPerWord = 0x40016b03 iocRdMaxSpeedHz = 0x80046b04 iocWrMaxSpeedHz = 0x40046b04 iocRdMode32 = 0x80046b05 iocWrMode32 = 0x40046b05 ) // Constants used by iocMessage function. const ( // iocMessage0 is the length of a message of 0 length. Use the // iocMessage(n) function for an iocMessage of length n. iocMessage0 = 0x40006b00 sizeBits = 14 sizeShift = 16 sizeMask = ((1 << sizeBits) - 1) << sizeShift ) // maxTransferSize is the maximum size of a transfer. This is limited by the // `length uint32` in the iocTransfer struct. var maxTransferSize = math.MaxInt32 // iocMessage is an ioctl number for n Transfers. Since the ioctl number // contains the size of the message, it is not a constant. func iocMessage(n int) uint32 { size := uint32(n * binary.Size(iocTransfer{})) if n < 0 || size > (1< %d)", e.TxLen, e.TxMax) } // ErrRxOverflow is returned if the Transfer buffer is too large. type ErrRxOverflow struct { RxLen, RxMax int } // Error implements the error interface. func (e ErrRxOverflow) Error() string { return fmt.Sprintf("SPI rx buffer overflow (%d > %d)", e.RxLen, e.RxMax) } // ErrBufferMismatch is returned if the rx and tx buffers do not have equal // length. type ErrBufferMismatch struct { TxLen, RxLen int } // Error implements the error interface. func (e ErrBufferMismatch) Error() string { return fmt.Sprintf("SPI tx and rx buffers of unequal length (%d != %d)", e.TxLen, e.RxLen) } // SPI wraps the Linux device driver and provides low-level SPI operations. type SPI struct { f *os.File // Used for mocking. syscall func(trap, a1, a2 uintptr, a3 unsafe.Pointer) (r1, r2 uintptr, err unix.Errno) // logger allows logging logger func(string, ...any) } type opt func(s *SPI) error // WithLogger returns an opt which can be used in Open to add // a logger. A common usage would be: // spidev.Open("/dev/spidev0.0", WithLogger(log.Printf)) func WithLogger(l func(string, ...any)) opt { return func(s *SPI) error { s.logger = l return nil } } // safe tries to set "safe" settings for initial SPI operation. // However, settings may not succeed, for $REASONS$. // Hardware is highly variable. // If there is an error, log it, and continue. func (s *SPI) safe() { if err := s.SetSpeedHz(500000); err != nil { s.logger("warning only: set speed to %d HZ err %v", 500000, err) } } // Open opens a new SPI device. dev is a filename such as "/dev/spidev0.0". // Remember to call Close() once done. func Open(dev string, opts ...opt) (*SPI, error) { f, err := os.OpenFile(dev, os.O_RDWR, 0) if err != nil { return nil, err } s := &SPI{ f: f, logger: func(string, ...any) {}, // log.Printf, //logger: log.Printf, // a3 must be an unsafe.Pointer instead of a uintptr, otherwise // we cannot mock out in the test without creating a race // condition. See `go doc unsafe.Pointer`. syscall: func(trap, a1, a2 uintptr, a3 unsafe.Pointer) (r1, r2 uintptr, err unix.Errno) { return unix.Syscall(trap, a1, a2, uintptr(a3)) }, } for _, o := range opts { if err := o(s); err != nil { return nil, err } } s.safe() return s, nil } // Close closes the SPI device. func (s *SPI) Close() error { return s.f.Close() } // Transfer performs multiple SPI reads and/or writes in a single function. // See the Transfer struct for details. func (s *SPI) Transfer(transfers []Transfer) error { // Convert []Transfer to []iocTransfer. it := make([]iocTransfer, len(transfers)) for i, t := range transfers { s.logger("%d:%s", i, t.String()) it[i] = iocTransfer{ speedHz: t.SpeedHz, delayUSecs: t.DelayUSecs, bitsPerWord: t.BitsPerWord, txNBits: t.TxNBits, rxNBits: t.RxNBits, wordDelayUSecs: t.WordDelayUSecs, } if len(t.Tx) > maxTransferSize { return ErrTxOverflow{len(t.Tx), maxTransferSize} } if len(t.Rx) > maxTransferSize { return ErrRxOverflow{len(t.Rx), maxTransferSize} } if len(t.Tx) != 0 && len(t.Rx) != 0 && len(t.Tx) != len(t.Rx) { return ErrBufferMismatch{len(t.Tx), len(t.Rx)} } if len(t.Tx) != 0 { txBuf := &transfers[i].Tx[0] it[i].txBuf = uint64(uintptr(unsafe.Pointer(txBuf))) it[i].length = uint32(len(t.Tx)) // Defer garbage collection until after the syscall. defer runtime.KeepAlive(txBuf) } if len(t.Rx) != 0 { rxBuf := &transfers[i].Rx[0] it[i].rxBuf = uint64(uintptr(unsafe.Pointer(rxBuf))) it[i].length = uint32(len(t.Rx)) // Defer garbage collection until after the syscall. defer runtime.KeepAlive(rxBuf) } if transfers[i].CSChange { it[i].csChange = 1 } } if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), uintptr(iocMessage(len(transfers))), unsafe.Pointer(&it[0])); err != 0 { return os.NewSyscallError("ioctl(SPI_IOC_MESSAGE)", err) } return nil } // Mode returns the Mode bitset. func (s *SPI) Mode() (Mode, error) { var m Mode if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), iocRdMode32, unsafe.Pointer(&m)); err != 0 { return 0, os.NewSyscallError("ioctl(SPI_IOC_RD_MODE32)", err) } return m, nil } // SetMode sets the Mode bitset. func (s *SPI) SetMode(m Mode) error { if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), iocWrMode32, unsafe.Pointer(&m)); err != 0 { return os.NewSyscallError("ioctl(SPI_IOC_WR_MODE32)", err) } return nil } // BitsPerWord sets the number of bits per word. Myy understanding is this is // only useful if there is a word delay. func (s *SPI) BitsPerWord() (uint8, error) { var bpw uint8 if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), iocRdBitsPerWord, unsafe.Pointer(&bpw)); err != 0 { return bpw, os.NewSyscallError("ioctl(SPI_IOC_RD_BITS_PER_WORD)", err) } return bpw, nil } // SetBitsPerWord sets the number of bits per word. func (s *SPI) SetBitsPerWord(bpw uint8) error { if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), iocWrBitsPerWord, unsafe.Pointer(&bpw)); err != 0 { return os.NewSyscallError("ioctl(SPI_IOC_WR_BITS_PER_WORD)", err) } return nil } // SpeedHz gets the transfer speed. func (s *SPI) SpeedHz() (uint32, error) { var hz uint32 if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), iocRdMaxSpeedHz, unsafe.Pointer(&hz)); err != 0 { return hz, os.NewSyscallError("ioctl(SPI_IOC_RD_MAX_SPEED_HZ)", err) } return hz, nil } // SetSpeedHz sets the transfer speed. func (s *SPI) SetSpeedHz(hz uint32) error { if _, _, err := s.syscall(unix.SYS_IOCTL, s.f.Fd(), iocWrMaxSpeedHz, unsafe.Pointer(&hz)); err != 0 { return os.NewSyscallError("ioctl(SPI_IOC_WR_MAX_SPEED_HZ)", err) } return nil }