If you want to write code which accesses SMBus devices, you should compile
the SMBus code as a separate module. This can be done by setting SMBUS_MODULE
to 1 in the Makefile. Remember to do a 'make clean' first!

Below you can find an explanation about the exported SMBus functions which
you can use in your own modules. To use them, add the line
  #include <linux/smbus.h>
to your programs.

At the bottom is an explanation of the syscall which can be used to access
SMBus devices from userspace.


MODULE FUNCTIONS
================

int SMBus_Init(void);
  This function is called by init_module. Do not use it.

int SMBus_Cleanup(void);
  This function is called by cleanup_module. Do not use it.

int SMBus_Initialized;
  0 if it was not initialized; calling any of the other functions may result
  in angry kernel messages.

int check_smb(u8 address);
  This function checks whether an SMBus address is already in use. It returns
  0 if can be grabbed, -EBUSY if it is already reserved. Compare check_region.

void request_smb(u8 address, const char *name);
  This function reserves an SMBus address. You should first have called
  check_smb to check it was free. If it could bot be grabbed, nothing happens.
  Note that name is not copied, so it must remain accessible throughout
  the livetime of this reservation. Compare request_region.

void release_smb(u8 address);
  Release the reservation of an SMBus address. If it was not reserved, nothing
  happens. Compare release_region.

int SMBus_Access(u8 addr, char read_write, u8 command, int size, 
                 union SMBus_Data *data);
  Read or write data from/to an SMBus device. This function works exactly
  like the syscall smbus_action (see below), except it does not check its
  arguments as rigorously. You will probably want to use any of the nicer
  access functions below.

int SMBus_Write_Quick(u8 addr,u8 value);
  Send a quick write command to the device at SMBus address 'addr'. 'command'
  is 1 bit long (on/off). Returns 0 on success, -1 on failure.

int SMBus_Read_Byte(u8 addr);
  Send a read command to the device at SMBus address 'addr'. Returns -1 on
  failure, or a 8 bit result on success.

int SMBus_Write_Byte(u8 addr, u8 value);
  Send a write command to the device at SMBus address 'addr'. 'value' is 8
  bits long.  Returns -1 on failure, 0 on success.

int SMBus_Read_Byte_Data(u8 addr, u8 command);
  Send a read command to the device at SMBus address 'addr'. 'command' is
  8 bits long, and usually selects a register. Returns -1 on failure, or a
  8 bit result on success.

int SMBus_Write_Byte_Data(u8 addr, u8 command, u8 value);
  Send a write command to the device at SMBus address 'addr'. 'command' is
  8 bits long, and usually selects a register. 'value' is 8 bits long.
  Returns -1 on failure, or 0 on success.

int SMBus_Read_Word_Data(u8 addr, u8 command);
  Send a read command to the device at SMBus address 'addr'. 'command' is
  8 bits long, and usually selects a register. Returns -1 on failure, or a
  16 bit result on success.

int SMBus_Write_Word_Data(u8 addr, u8 command, u16 value);
  Send a write command to the device at SMBus address 'addr'. 'command' is
  8 bits long, and usually selects a register. 'value' is 16 bits long.
  Returns -1 on failure, or 0 on success.

int SMBus_Read_Block_Data(u8 addr, u8 command, char *valueptr);
  Read a block of values from the device at SMBus address 'addr'. 'command'
  is 8 bits long, and usually selects a register. The results are put in the
  array valueptr. Each value is 8 bits long. Returns -1 on failure, or
  the number of bytes put in valueptr on success.

int SMBus_Write_Block(u8 addr, u8 command, u8 length, const char *valueptr);
  Write a block of values to the device at SMBus address 'addr'. 'command'
  is 8 bits long, and usually selects a register. 'length' is the number
  of bytes to write; it may be 32 at most. The values are read from the
  array valueptr. Each value is 8 bits long. Returns -1 on failure, or
  0 on success.


SYSCALL
=======

If you want to access SMBus devices from userspace, use the following two
lines in your program:

#include <linux/smbus.h>
_syscall5(int, smbus_action,__u8,addr,char,read_write,__u8,command, 
          int,size,union SMBus_Data *,data);

After these lines, you have the following definition of smbus_action:

int smbus_action(__u8 addr, char read_write, __u8 command, int size,
                 struct SMBus_Data *data);

These are the parameters to smbus_action:

* The first is the SMBus address (7-bit). This must always be specified.

* The second is the SMBus operation (SMBUS_READ or SMBUS_WRITE). For
  SMBUS_QUICK transactions, it is the data to send.

* The third is the command byte. This usually chooses the 'register' in the
  device to read/modify. It is ignored for SMBUS_QUICK transactions. For 
  SMBUS_BYTE transactions, it is the data to send.

* The fourth is the transaction size which can be any size defined in
  smbus.h: SMBUS_QUICK, SMBUS_BYTE, SMBUS_BYTE_DATA, SMBUS_WORD_DATA or
  SMBUS_BLOCK_DATA.

* The fifth is a pointer to a SMBus_Data union. For a write, you put the
  values to write in here; for a read, you can read the values back after
  the syscall from here. 
  For SMBUS_QUICK transactions, and SMBUS_BYTE writes, this field is
  ignored.
  For SMBUS_BYTE reads and SMBUS_BYTE_DATA transactions, the byte field is used
  (8 bits long).
  For SMBUS_WORD_DATA transactions, the word field is used (16 bits long).
  For SMBUS_BLOCK_DATA transactions, the block field is used. Each element
  of this array is 8 bits long. The first element is the number of remaining
  elements in the array (ie. to write 5 bytes, make block[0] equal 5, and
  put the elements in block[1] to block[5]).

Lastly, the function returns 0 for no errors, and -1 if an error occured.
"errno" must be checked to see what the error is (as listed in
linux/include/asm/errno.h).

That's it!

Because the direct use of the syscall is not very user-friendly, a couple
of macros (well, actually they are inline functions) are defined. If you
want to use these, you *must* use at least -O1 to compile the files they
are used in!

int SMBus_Write_Quick(__u8 addr, __u8 value)
int SMBus_Read_Byte(__u8 addr)
int SMBus_Write_Byte(__u8 addr, __u8 value)
int SMBus_Read_Byte_Data(__u8 addr, __u8 command)
int SMBus_Write_Byte_Data(__u8 addr, __u8 command, __u8 value)
int SMBus_Read_Word_Data(__u8 addr, __u8 command)
int SMBus_Write_Word_Data(__u8 addr, __u8 command, __u16 value)
int SMBus_Read_Block_Data(__u8 addr, __u8 command, char *values)
int SMbus_Write_Block_Data(__u8 addr, __u8 command, __u8 length, char *values) 

These functions return -1 if the syscall failed (check errno to find out why).
The Write variants return 0 on success; the Read variants return the read
value (in case of SMBus_Read_Block_Data: the total number of bytes read).
Be careful with SMBus_Read_Block_Data: there can be upto 32 bytes put in 
*values.
