Now that I learned about how all this is working together, quickly

document it for anyone else who might be interested in it.

MFC after:	2 weeks

1 files changed, 147 insertions, 15 deletions

diff --git a/share/man/man4/smb.4 b/share/man/man4/smb.4
index 0a9075e..8645c03 100644
--- a/share/man/man4/smb.4
+++ b/share/man/man4/smb.4
@@ -1,4 +1,5 @@
 .\" Copyright (c) 1998, Nicolas Souchu
+.\" Copyright (c) 2004, Joerg Wunsch
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -38,26 +39,157 @@ The
 character device driver provides generic i/o to any
 .Xr smbus 4
 instance.
-In order to control SMB devices, use /dev/smb? with the
-following ioctls:
+In order to control SMB devices, use
+.Pa /dev/smb Ns Em ?
+with the ioctls described below.
+Any of these ioctl commands takes a pointer to
+.Vt struct smbcmd
+as its argument.
 .Pp
-.Bl -column "System Management Bus ioctls" -compact
+.Bd -literal
+#include <sys/types.h>
+
+struct smbcmd {
+	char cmd;
+	int count;
+	u_char slave;
+	union {
+		char byte;
+		short word;
+
+		char *byte_ptr;
+		short *word_ptr;
+
+		struct {
+			short sdata;
+			short *rdata;
+		} process;
+	} data;
+};
+.Ed
+.Pp
+The
+.Fa slave
+field is always used, and provides the address of the
+SMBus slave device to talk to.
+.Pp
+.Bl -column ".Sy SMB_QUICK_WRITE" -compact
 .It Em Ioctl Ta Em Description
-.It Sy SMB_QUICK_WRITE Ta "QuickWrite command"
-.It Sy SMB_QUICK_READ Ta "QuickRead command"
-.It Sy SMB_SENDB Ta "SendByte command"
-.It Sy SMB_RECVB Ta "ReceiveByte command"
-.It Sy SMB_WRITEB Ta "WriteByte command"
-.It Sy SMB_WRITEW Ta "WriteWord command"
-.It Sy SMB_READB Ta "ReadByte command"
-.It Sy SMB_READW Ta "ReadWord command"
-.It Sy SMB_PCALL Ta "ProcedureCall command"
-.It Sy SMB_BWRITE Ta "BlockWrite command"
-.It Sy SMB_BREAD Ta "BlockRead command"
+.Pp
+.It Sy SMB_QUICK_WRITE Ta
+The
+.Em QuickWrite
+command just issues the device address with write intent
+to the bus, without transferring any data.
+.It Sy SMB_QUICK_READ Ta
+The
+.Em QuickRead
+command just issues the device address with read intent
+to the bus, without transferring any data.
+.It Sy SMB_SENDB Ta
+The
+.Em SendByte
+command sends the byte provided in the
+.Fa cmd
+field to the device.
+.It Sy SMB_RECVB Ta
+The
+.Em ReceiveByte
+command reads a single byte from the device which will
+be returned in the
+.Fa cmd
+field.
+.It Sy SMB_WRITEB Ta
+The
+.Em WriteByte
+command first sends the byte from the
+.Fa cmd
+field to the device, followed by the byte given in
+.Fa data.byte .
+.It Sy SMB_WRITEW Ta
+The
+.Em WriteWord
+command first sends the byte from the
+.Fa cmd
+field to the device, followed by the word given in
+.Fa data.word .
+Note that the SMBus byte-order is little-endian by definition.
+.It Sy SMB_READB Ta
+The
+.Em ReadByte
+command first sends the byte from the
+.Fa cmd
+field to the device, and then reads one byte of data from
+the device.
+The returned data will be stored in the location pointed to by
+.Fa data.byte_ptr .
+.It Sy SMB_READW Ta
+The
+.Em ReadWord
+command first sends the byte from the
+.Fa cmd
+field to the device, and then reads one word of data from
+the device.
+The returned data will be stored in the location pointed to by
+.Fa data.word_ptr .
+.It Sy SMB_PCALL Ta
+The
+.Em ProcedureCall
+command first sends the byte from the
+.Fa cmd
+field to the device, followed by the word provided in
+.Fa data.process.sdata .
+It then reads one word of data from the device, and returns it
+in the location pointed to by
+.Fa data.process.rdata .
+.It Sy SMB_BWRITE Ta
+The
+.Em BlockWrite
+command first sends the byte from the
+.Fa cmd
+field to the device, followed by
+.Fa count
+bytes of data that are taken from the buffer pointed to by
+.Fa data.byte_ptr .
+The SMBus specification mandates that no more than 32 bytes of
+data can be transferred in a single block read or write command.
+This value is available in the constant
+.Dv SMB_MAXBLOCKSIZE .
+.It Sy SMB_BREAD Ta
+The
+.Em BlockRead
+command first sends the byte from the
+.Fa cmd
+field to the device, and then reads
+.Fa count
+bytes of data that from the device.
+These data will be returned in the buffer pointed to by
+.Fa data.byte_ptr .
 .El
 .Pp
-Using the write routine is equivalent to a SMB_WRITEW ioctl.
+The
+.Xr read 2
+and
+.Xr write 2
+system calls are not implemented by this driver.
+.Sh ERRORS
+The
+.Xr ioctl
+commands can cause the following driver-specific errors:
+.Bl -tag -width Er
+.It Bq Er ENXIO
+Device did not respond to selection.
+.It Bq Er EBUSY
+Device still in use.
+.It Bq Er ENODEV
+Operation not supported by device (not supposed to happen).
+.It Bq Er EINVAL
+General argument error.
+.It Bq Er EWOULDBLOCK
+SMBus transaction timed out.
+.El
 .Sh SEE ALSO
+.Xr ioctl 2 ,
 .Xr smbus 4
 .Sh HISTORY
 The