Changeset 14

Show
Ignore:
Timestamp:
11/26/98 11:55:26 (10 years ago)
Author:
frodo
Message:

update of doc/design; it now reflects the code again (which is nice
for a design document :-) ).

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • lm-sensors/trunk/TODO

    r13 r14  
    1414* Write a userland detection program for busses (clients are less important; 
    1515  but perhaps needed too). 
    16 * Bring doc/design up-to-date (it is horribly out of date right now) 

  • lm-sensors/trunk/doc/design

    r12 r14  
    77                 1.1, 19981111. 
    88                 1.2, 19981118. 
    9  
    10 --> Never, ever change the driver struct with this technique!  
     9                 1.3, 19981126. 
    1110 
    1211 
    …… 
    1615The i2c module structs contain callback functions and data fields. In the 
    1716i2c module, these structures are only referenced by pointers. This makes 
    18 is easy to extend these structs to contain additional information or 
     17it easy to extend these structs to contain additional information or 
    1918callback functions. For those familiar with object oriented languages, 
    20 you can see the smbus structures as an object extension of the i2c 
    21 structures, and the sensors structures are an extenstion of the smbus 
     19you can see the smbus and isa structures as an object extension of the i2c 
    2220structures. 
    2321 
    …… 
    3634We have a plain data field (name), a call-back function which needs one 
    3735parameter (a pointer to a i2c_client struct), and a data field which is 
    38 a pointer to the next adapater. 
     36a pointer to the next adapter. 
    3937 
    4038Now we want to extend this structure. We need another data field, 
    …… 
    9896and basing anything upon their module much more difficult. 
    9997 
     98Limitations 
     99----------- 
     100 
     101Extending the adapter and algorithm structures in this way is quite safe. 
     102They are only allocated on places where the code knows that they are 
     103'special'. Extending the driver or client structures depending on a 
     104specific adapter/algorithm type is *very* *dangerous*. A driver/client 
     105module would need to be aware of every special adapter/algorithm in 
     106order to allocate itself! For the ISA bus, it has to be aware of this 
     107anyway, so it is safe to do; on other places, think twice first! 
     108 
    100109 
    101110Module overview 
    …… 
    104113All in all, lots of modules will be stacked on each other. Too bad, but 
    105114that is the only way to cleanly implement everything. Note that in a 
    106 specific situation, only a few modules may need to be loaded. sensor.o, 
     115specific situation, only a few modules may need to be loaded. isa.o, 
    107116for example, does not depend on smbus.o (in the sense that you can load 
    108117sensor.o without loading smbus.o). A specific bus driver, though, will 
    …… 
    110119 
    111120Generally: 
    112   sensor.o depends on nothing 
    113   smbus.o depends on nothing 
     121  isa.o depends on nothing (actually, on i2c.o, to keep the code small) 
     122  smbus.o depends on nothing (actually, on i2c.o, to keep the code small) 
    114123  i2c.o depends on nothing. 
    115124 
    116   isa.o depends only on sensor.o 
    117125  A non-i2c SMBus bus driver depends only on smbus.o 
    118126  A i2c bus driver depends only on i2c.o 
    119127 
    120   A sensor chip driver depends at least on sensor.o, and possibly on smbus.o 
     128  A sensor chip driver depends either on isa.o or smbus.o, or both. 
    121129  A SMBus chip driver depends only on smbus.o 
    122130  A I2C chip driver depends only on i2c.o 
    123131 
    124  
    125 sensor.o 
    126 Main sensors handling 
    127 Unites SMBus adapters and ISA adapters. 
    128  
    129   isa.o 
    130   Implements the ISA adapter driver for sensor.o. This may prove to be so 
    131   closely integrated that it can better be made part of sensor.o 
    132    
     132We may need a sensor.o module, to act as a central point for sensor 
     133modules. At this moment, it seems not really necessary, but this may 
     134change. 
     135 
     136We will need an enhanced i2c-dev.o module, to add SMBus access to I2C 
     137/dev entries. 
     138 
     139 
     140isa.o 
     141ISA bus handling. 
     142Encapsulates ISA bus access within the i2c structures. 
     143Unites I2C adapters and the ISA bus. 
     144Defines variables isa_algorithm and isa_adapter. 
    133145 
    134146smbus.o 
    135 Main SMBus handling 
    136 Unites I2C adapters and SMBus hosts (like the PIIX4) 
    137 Defines smbus_algorithm 
     147Main SMBus handling. 
     148Encapsulates SMBus access within the smbus structures. 
     149Unites I2C adapters and SMBus hosts (like the PIIX4). 
     150Emulates SMBus access on pure I2C adapters. 
     151Defines variable smbus_algorithm. 
    138152 
    139153  piix4.o 
    140154  SMBus adapter driver for the PIIX4 SMBus host. 
    141  
    142   ????.o 
    143   Adapter driver for another SMBus host 
    144  
    145  
    146 i2c.o                
    147 Main i2c handling 
     155  Defines variable piix4_adapter (based on smbus_algorithm). 
     156 
     157  FOO.o 
     158  Adapter driver for FOO SMBus host 
     159  Defines variable FOO_adapter (based on smbus_algorithm). 
     160 
     161i2c-core.o (From Simon Vogl) 
     162Main i2c handling. 
    148163 
    149164  ????.o 
    …… 
    154169A chip driver (typically defined in its own module) can be hooked on all 
    155170these levels: 
    156   * If it is a sensor chip, it should be hooked to sensor.o 
    157   * An SMBus chip should be hooked to smbus.o 
     171  * If it is a sensor chip, it should be hooked to isa.o or smbus.o 
     172  * A pure ISA chip should be hooked to isa.o 
     173  * A pure SMBus chip should be hooked to smbus.o 
    158174  * An I2C chip should be hooked to i2c.o 
    159 It can be difficult to decide whether a specific chip should be hoooked to 
     175It can be difficult to decide whether a specific chip should be hooked to 
    160176smbus.o or i2c.o. A good deciding question is, 'could it be connected to 
    161177a PIIX4?' 
    …… 
    192208  name: The name of this driver 
    193209  id: A unique driver identifier 
    194   flags: Flags to set certain kinds of behaviour (not used right now) 
     210  flags: Flags to set certain kinds of behaviour. Most notably, DF_NOTIFY 
     211    will notify the driver when a new i2c bus is detected, so it can 
     212    try to detect chips on it. 
    195213  attach_adapter: A call-back function which is called if a new adapter (bus) 
    196214    is found. This allows us to do our detection stuff on the new adapter, 
    …… 
    318336 
    319337 
    320 There are several other functions, to register things for example, that 
    321 are less important to us. 
     338Administration functions 
     339------------------------ 
     340 
     341int i2c_add_algorithm(struct i2c_algorithm *); 
     342int i2c_del_algorithm(struct i2c_algorithm *); 
     343 
     344The i2c_{add,del}_algorithm functions must be called whenever a new module 
     345is inserted with this driver in it, by the module initialization function. 
     346 
     347 
     348int i2c_add_adapter(struct i2c_adapter *); 
     349int i2c_del_adapter(struct i2c_adapter *); 
     350 
     351The i2c_{add,del}_adapter functions must be called if you have detected 
     352a specific bus. It triggers driver->attach_adapter (add, for each driver 
     353present) or driver->detach_client (del, for each registered client on 
     354this adapter). 
     355 
     356 
     357int i2c_add_driver(struct i2c_driver *); 
     358int i2c_del_driver(struct i2c_driver *); 
     359 
     360The i2c_{add,del}_driver functions must be called whenever a new module is 
     361inserted with a chip driver in it, by the module initialization function. 
     362 
     363 
     364int i2c_attach_client(struct i2c_client *); 
     365int i2c_detach_client(struct i2c_client *); 
     366 
     367The i2c_{attach,detach}_client functions must be called if you have detected 
     368a single chip. 
    322369 
    323370 
    …… 
    337384we can add a hook somewhere in the i2c module to help us decide this. 
    338385 
    339 This module consists in fact of two separate parts: first of all, it extends 
     386This module consists in fact of three separate parts: first of all, it extends 
    340387all i2c structs to accomodate the new smbus fields. Second, it defines a 
    341388new algorithm (smbus_algorithm), that will be used by all non-i2c adapters. 
     389Finally, it implements a new access function that sends or receives SMBus 
     390commands; these are either translated into I2C commands or sent to the 
     391SMBus driver. 
    342392 
    343393 
    …… 
    376426  int retries; 
    377427 
    378   /* Here ended i2c_algorithm */ 
     428  /* Here ended i2c_adapter */ 
    379429  s32 (* smbus_access) (__u8 addr, char read_write, 
    380430                        __u8 command, int size, union smbus_data * data); 
    …… 
    396446on it: 
    397447 
    398 int smbus_access (struct smbus_adapter *, __u8 addr, char read_write, 
     448int smbus_access (struct i2c_adapter *, __u8 addr, char read_write, 
    399449                  __u8 command, int size, union smbus_data * data); 
    400450 
    401 There will be specific SMBus registration functions too, like the i2c 
    402 ones.  
    403  
    404  
    405 Module sensors.o 
    406 ================ 
    407  
    408 This module acts as a coordinations point between specific sensor modules 
    409 (which each support a certain kind of sensor). We need this module to unite 
    410 SMBus access and ISA access.  
    411  
    412  
    413 A driver or adapter 
    414 ------------------- 
    415  
    416 We will not need to extend smbus_driver or smbus_adapter. This means that 
    417 struct sensor_driver is exactly the same as struct smbus_driver, and struct 
    418 sensor_adapter is the same as struct smbus_adapter. We *will* define the 
    419 sensor_* variants, and use them within this module, so it should be easy to 
    420 extend them after all. 
    421  
    422 Note that a driver can be for a chip on either the ISA bus or the 
    423 I2C/SMBus. If a specific chip can be on both, you must check variable 
    424 client->adapter->algorithm->on_isa to determine which bus you need to access. 
     451There are specific SMBus registration functions too, like the i2c ones.  
     452They are fully compatiable with each other; just substitute 'smbus' for 
     453'i2c' everywhere in the i2c description. 
     454 
     455int i2c_is_smbus_client(struct i2c_client *); 
     456int i2c_is_smbus_adapter(struct i2c_adapter *); 
     457 
     458Decide whether this client, or adapter, is (on) a non-I2C SMBus. Usually 
     459not needed, but it is nice anyway to be able to decide this. 
     460 
     461 
     462Module isa.o 
     463============ 
     464 
     465This module implements a new algorithm and a specific adapter for the 
     466(single) ISA bus in your computer. This makes writing drivers for chips 
     467that can be both on ISA and SMBus much easier. 
     468 
     469Note that this module does *not* in any way depend on smbus.o (previous 
     470versions of this document still assumed it would be build upon it; this 
     471is no longer true). 
     472 
     473 
     474A driver, adapter or algorithm 
     475------------------------------ 
     476 
     477We will not need to extend i2c_driver, i2c_adapter or i2c_algorithm. This 
     478means that struct isa_driver is exactly the same as struct i2c_driver, 
     479struct isa_adapter is the same as struct i2c_adapter and struct isa_algorithm 
     480is the same as struct isa_driver. We *will* define the isa_* variants, and 
     481use them within this module, so it should be easy to extend them after all. 
    425482 
    426483 
    …… 
    428485-------- 
    429486 
    430 struct sensor_client { 
     487struct isa_client { 
    431488  char name[32]; 
    432489  int id; 
    433490  unsigned int flags; 
    434491  unsigned char addr; 
    435   struct sensor_adapter *adapter; 
    436   struct sensor_driver *driver; 
     492  struct isa_adapter *adapter; 
     493  struct isa_driver *driver; 
    437494  void *data; 
    438495 
    439   unsigned int full_address; 
     496  unsigned int isa_addr; 
    440497} 
    441498 
    442499A client is a specific sensor chip. Its operation is controlled by a driver 
    443500(which describes a type of sensor chip), and it is connected to an adapter 
    444 (a bus, either a I2C/SMBus or the ISA bus). 
     501(a bus, the (single) ISA bus here). 
    445502 
    446503A description of the above struct: 
    447   full_address: The full client address. ISA addresses and 10-bit SMBus 
    448     addresses do not fit in the i2c-compatible addr field, so we needed 
    449     a new field. 
    450  
    451  
    452  
    453 An algorithm 
    454 ------------ 
    455  
    456 struct sensor_algorithm { 
    457   char name[32]; 
    458   unsigned int id; 
    459   int (* master_xfer) (struct sensor_adapter *adap, struct smbus_msg msgs[], 
    460                        int num); 
    461   int (* slave_send) (struct sensor_adapter *,char *, int); 
    462   int (* slave_recv) (struct sensor_adapter *,char *, int); 
    463   int (* algo_control) (struct sensor_adapter *, unsigned int, unsigned long); 
    464   int (* client_register) (struct sensor_client *); 
    465   int (* client_unregister) (struct sensor_client *); 
    466  
    467   int (* smbus_access) (struct sensor_adapter *, __u8 addr, char read_write, 
    468                         __u8 command, int size, union smbus_data * data); 
    469   int isa_bus; 
    470 } 
    471  
    472 A description of the above struct: 
    473   isa_bus: 0 if this structure describes SMBus access, 1 if it describes 
    474     ISA access. 
    475  
    476 In case of the ISA bus, the master_xfer, slave_send, slave_recv and 
    477 smbus_access hooks will be NULL, because these functions make no sense. 
    478 It is regrettably not easy to create an access abstraction in which both 
    479 ISA bus access and SMBus access are united. See below for examples how 
    480 you can solve this problem. 
     504  isa_addr: ISA addresses do not fit in the i2c-compatible addr field, so 
     505    we needed a new field. 
    481506 
    482507 
    …… 
    486511All these functions are defined extern. 
    487512 
     513In case of the ISA bus, the master_xfer, slave_send and slave_recv hooks 
     514will be NULL, because these functions make no sense. It is regrettably 
     515not easy to create an access abstraction in which both ISA bus access 
     516and SMBus access are united. See below for examples how you can solve 
     517this problem. 
     518 
    488519The most imporant additional access function: 
    489520 
    490   int is_on_isa (struct sensor_client *); 
    491  
    492 This function tells us whether a specific client is connected to the ISA 
    493 bus or to the SMBus. This is important, because it determines whether we 
    494 can use the SMBus access routines. 
     521int i2c_is_isa_client(struct i2c_client *); 
     522int i2c_is_isa_adapter(struct i2c_adapter *); 
     523 
     524Decide whether this client, or adapter, is (on) the ISA bus. This is 
     525important, because it determines whether we can use the SMBus access 
     526routines. 
    495527 
    496528As an example, I will here implement our old LM78 access function: 
    497529 
    498 u8 lm78_read_value(struct sensor_client *client, u8 register) 
     530/* The SMBus locks itself, but ISA access must be locked explicitely! 
     531   We ignore the LM78 BUSY flag at this moment - it could lead to deadlocks, 
     532   would slow down the LM78 access and should not be necessary. 
     533   There are some ugly typecasts here, but the good new is - they should 
     534   nowhere else be necessary! */ 
     535int lm78_read_value(struct i2c_client *client, u8 reg) 
    499536{ 
    500   if (is_on_isa(client)) { 
    501     /* Ignore the check for LM78_BUSY to keep things simple here; the best 
    502        place to put this semaphore struct would be in client->data */ 
    503     outb_p(register,client->address + LM78_ADDR_REG_OFFSET); 
    504     return inb_p(client->address + LM78_DATA_REG_OFFSET); 
    505   } else  
    506     return smbus_read_byte_data(client,register); 
    507     /* This is a standard function based on smbus_access */ 
    508 } 
    509  
    510  
     537  int res; 
     538  if (i2c_is_isa_client(client)) { 
     539    down((struct semaphore *) (client->data)); 
     540    outb_p(reg,(((struct isa_client *) client)->isa_addr) + 
     541               LM78_ADDR_REG_OFFSET); 
     542    res = inb_p((((struct isa_client *) client)->isa_addr) + 
     543                LM78_DATA_REG_OFFSET); 
     544    up((struct semaphore *) (client->data)); 
     545    return res; 
     546  } else 
     547    return smbus_read_byte_data(client->adapter,client->addr, reg); 
     548}