Explorar el Código

Doxygenation

tags/v0.9.3
Michael Brown hace 19 años
padre
commit
f88c0d42d5
Se han modificado 1 ficheros con 196 adiciones y 58 borrados
  1. 196
    58
      src/drivers/bus/isapnp.c

+ 196
- 58
src/drivers/bus/isapnp.c Ver fichero

33
 *
33
 *
34
 ***************************************************************************/
34
 ***************************************************************************/
35
 
35
 
36
-#include "string.h"
37
-#include "timer.h"
38
-#include "io.h"
39
-#include "console.h"
40
-#include "isapnp.h"
41
-
42
-/*
43
- * We can have only one ISAPnP bus in a system.  Once the read port is
44
- * known and all cards have been allocated CSNs, there's nothing to be
45
- * gained by re-scanning for cards.
36
+/** @file
37
+ *
38
+ * ISAPnP bus support
39
+ *
40
+ * Etherboot orignally gained ISAPnP support in a very limited way for
41
+ * the 3c515 NIC.  The current implementation is almost a complete
42
+ * rewrite based on the ISAPnP specification, with passing reference
43
+ * to the Linux ISAPnP code.
44
+ *
45
+ * There can be only one ISAPnP bus in a system.  Once the read port
46
+ * is known and all cards have been allocated CSNs, there's nothing to
47
+ * be gained by re-scanning for cards.
46
  *
48
  *
47
  * However, we shouldn't make scanning the ISAPnP bus an INIT_FN(),
49
  * However, we shouldn't make scanning the ISAPnP bus an INIT_FN(),
48
  * because even ISAPnP probing can still screw up other devices on the
50
  * because even ISAPnP probing can still screw up other devices on the
50
  * an ISAPnP device.
52
  * an ISAPnP device.
51
  *
53
  *
52
  * External code (e.g. the ISAPnP ROM prefix) may already know the
54
  * External code (e.g. the ISAPnP ROM prefix) may already know the
53
- * read port address, in which case it can initialise this value.
54
- * Note that setting the read port address will prevent further
55
- * isolation from taking place; you should set the read port address
56
- * only if you know that devices have already been allocated CSNs.
55
+ * read port address, in which case it can store it in @c
56
+ * isapnp_read_port.  Note that setting the read port address in this
57
+ * way will prevent further isolation from taking place; you should
58
+ * set the read port address only if you know that devices have
59
+ * already been allocated CSNs.
60
+ *
61
+ */
62
+
63
+#include "string.h"
64
+#include "timer.h"
65
+#include "io.h"
66
+#include "console.h"
67
+#include "isapnp.h"
68
+
69
+/**
70
+ * ISAPnP Read Port address.
57
  *
71
  *
58
  */
72
  */
59
 uint16_t isapnp_read_port;
73
 uint16_t isapnp_read_port;
60
 
74
 
61
-/*
75
+/**
62
  * Highest assigned CSN.
76
  * Highest assigned CSN.
63
  *
77
  *
64
- * Note that *we* do not necessarily assign CSNs; it could be done by
78
+ * Note that @b we do not necessarily assign CSNs; it could be done by
65
  * the PnP BIOS instead.  We therefore set this only when we first try
79
  * the PnP BIOS instead.  We therefore set this only when we first try
66
  * to Wake[CSN] a device and find that there's nothing there.  Page 16
80
  * to Wake[CSN] a device and find that there's nothing there.  Page 16
67
  * (PDF page 22) of the ISAPnP spec states that "Valid Card Select
81
  * (PDF page 22) of the ISAPnP spec states that "Valid Card Select
116
 		 + isapnp_read_byte ( address + 1 ) );
130
 		 + isapnp_read_byte ( address + 1 ) );
117
 }
131
 }
118
 
132
 
133
+/** Inform cards of a new read port address */
119
 static inline void isapnp_set_read_port ( void ) {
134
 static inline void isapnp_set_read_port ( void ) {
120
 	isapnp_write_byte ( ISAPNP_READPORT, isapnp_read_port >> 2 );
135
 	isapnp_write_byte ( ISAPNP_READPORT, isapnp_read_port >> 2 );
121
 }
136
 }
122
 
137
 
138
+/**
139
+ * Enter the Isolation state.
140
+ *
141
+ * Only cards currently in the Sleep state will respond to this
142
+ * command.
143
+ *
144
+ */
123
 static inline void isapnp_serialisolation ( void ) {
145
 static inline void isapnp_serialisolation ( void ) {
124
 	isapnp_write_address ( ISAPNP_SERIALISOLATION );
146
 	isapnp_write_address ( ISAPNP_SERIALISOLATION );
125
 }
147
 }
126
 
148
 
149
+/**
150
+ * Enter the Wait for Key state.
151
+ *
152
+ * All cards will respond to this command, regardless of their current
153
+ * state.
154
+ *
155
+ */
127
 static inline void isapnp_wait_for_key ( void ) {
156
 static inline void isapnp_wait_for_key ( void ) {
128
 	isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_WAIT_FOR_KEY );
157
 	isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_WAIT_FOR_KEY );
129
 }
158
 }
130
 
159
 
160
+/**
161
+ * Reset (i.e. remove) Card Select Number.
162
+ *
163
+ * Only cards currently in the Sleep state will respond to this
164
+ * command.
165
+ *
166
+ */
131
 static inline void isapnp_reset_csn ( void ) {
167
 static inline void isapnp_reset_csn ( void ) {
132
 	isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_RESET_CSN );
168
 	isapnp_write_byte ( ISAPNP_CONFIGCONTROL, ISAPNP_CONFIG_RESET_CSN );
133
 }
169
 }
134
 
170
 
171
+/**
172
+ * Place a specified card into the Config state.
173
+ *
174
+ * @v csn		Card Select Number
175
+ * @ret None
176
+ * @err None
177
+ *
178
+ * Only cards currently in the Sleep, Isolation, or Config states will
179
+ * respond to this command.  The card that has the specified CSN will
180
+ * enter the Config state, all other cards will enter the Sleep state.
181
+ *
182
+ */
135
 static inline void isapnp_wake ( uint8_t csn ) {
183
 static inline void isapnp_wake ( uint8_t csn ) {
136
 	isapnp_write_byte ( ISAPNP_WAKE, csn );
184
 	isapnp_write_byte ( ISAPNP_WAKE, csn );
137
 }
185
 }
144
 	return isapnp_read_byte ( ISAPNP_STATUS );
192
 	return isapnp_read_byte ( ISAPNP_STATUS );
145
 }
193
 }
146
 
194
 
195
+/**
196
+ * Assign a Card Select Number to a card, and enter the Config state.
197
+ *
198
+ * @v csn		Card Select Number
199
+ * @ret None
200
+ * @err None
201
+ *
202
+ * Only cards in the Isolation state will respond to this command.
203
+ * The isolation protocol is designed so that only one card will
204
+ * remain in the Isolation state by the time the isolation protocol
205
+ * completes.
206
+ *
207
+ */
147
 static inline void isapnp_write_csn ( uint8_t csn ) {
208
 static inline void isapnp_write_csn ( uint8_t csn ) {
148
 	isapnp_write_byte ( ISAPNP_CARDSELECTNUMBER, csn );
209
 	isapnp_write_byte ( ISAPNP_CARDSELECTNUMBER, csn );
149
 }
210
 }
174
 	udelay ( 1000 );
235
 	udelay ( 1000 );
175
 }
236
 }
176
 
237
 
177
-/*
178
- * The linear feedback shift register as described in Appendix B of
179
- * the PnP ISA spec.  The hardware implementation uses eight D-type
180
- * latches and two XOR gates.  I think this is probably the smallest
181
- * possible implementation in software.  Six instructions when input_bit
182
- * is a constant 0 (for isapnp_send_key).  :)
238
+/**
239
+ * Linear feedback shift register.
240
+ *
241
+ * @v lfsr		Current value of the LFSR
242
+ * @v input_bit		Current input bit to the LFSR
243
+ * @ret lfsr		Next value of the LFSR
244
+ * @err None
245
+ *
246
+ * This routine implements the linear feedback shift register as
247
+ * described in Appendix B of the PnP ISA spec.  The hardware
248
+ * implementation uses eight D-type latches and two XOR gates.  I
249
+ * think this is probably the smallest possible implementation in
250
+ * software.  Six instructions when input_bit is a constant 0 (for
251
+ * isapnp_send_key).  :)
183
  *
252
  *
184
  */
253
  */
185
 static inline uint8_t isapnp_lfsr_next ( uint8_t lfsr, int input_bit ) {
254
 static inline uint8_t isapnp_lfsr_next ( uint8_t lfsr, int input_bit ) {
190
 	return lfsr_next;
259
 	return lfsr_next;
191
 }
260
 }
192
 
261
 
193
-/*
194
- * Send the ISAPnP initiation key
262
+/**
263
+ * Send the ISAPnP initiation key.
264
+ *
265
+ * Sending the key causes all ISAPnP cards that are currently in the
266
+ * Wait for Key state to transition into the Sleep state.
195
  *
267
  *
196
  */
268
  */
197
 static void isapnp_send_key ( void ) {
269
 static void isapnp_send_key ( void ) {
209
 	}
281
 	}
210
 }
282
 }
211
 
283
 
212
-/*
213
- *  Compute ISAPnP identifier checksum
284
+/**
285
+ * Compute ISAPnP identifier checksum
286
+ *
287
+ * @v identifier		ISAPnP identifier
288
+ * @ret checksum		Expected checksum value
289
+ * @err None
214
  *
290
  *
215
  */
291
  */
216
 static uint8_t isapnp_checksum ( struct isapnp_identifier *identifier ) {
292
 static uint8_t isapnp_checksum ( struct isapnp_identifier *identifier ) {
248
 	return 0xff;
324
 	return 0xff;
249
 }
325
 }
250
 
326
 
251
-/*
252
- * Read n bytes of resource data from the current location.  If buf is
253
- * NULL, discard data.
327
+/**
328
+ * Read resource data.
329
+ *
330
+ * @v buf		Buffer in which to store data, or NULL
331
+ * @v bytes		Number of bytes to read
332
+ * @ret None
333
+ * @err None
334
+ *
335
+ * Resource data is read from the current location.  If @c buf is NULL,
336
+ * the data is discarded.
254
  *
337
  *
255
  */
338
  */
256
 static void isapnp_peek ( uint8_t *buf, size_t bytes ) {
339
 static void isapnp_peek ( uint8_t *buf, size_t bytes ) {
265
 	}
348
 	}
266
 }
349
 }
267
 
350
 
268
-/*
269
- * Scan through the resource data until we find a particular tag, and
270
- * read its contents into a buffer.
351
+/**
352
+ * Find a tag within the resource data.
271
  *
353
  *
272
- * It is the caller's responsibility to ensure that buf is large
273
- * enough to contain a tag of the requested size.
354
+ * @v wanted_tag	The tag that we're looking for
355
+ * @v buf		Buffer in which to store the tag's contents
356
+ * @ret True		Tag was found
357
+ * @ret False		Tag was not found
358
+ * @err None
359
+ *
360
+ * Scan through the resource data until we find a particular tag, and
361
+ * read its contents into a buffer.  It is the caller's responsibility
362
+ * to ensure that @c buf is large enough to contain a tag of the
363
+ * requested size.
274
  *
364
  *
275
  */
365
  */
276
 static int isapnp_find_tag ( uint8_t wanted_tag, uint8_t *buf ) {
366
 static int isapnp_find_tag ( uint8_t wanted_tag, uint8_t *buf ) {
300
 	return 0;
390
 	return 0;
301
 }
391
 }
302
 
392
 
303
-/*
304
- * Try isolating ISAPnP cards at the current read port.  Return the
305
- * number of ISAPnP cards found.  <0 indicates "try a new read port",
306
- * 0 indicates "definitely no cards".
393
+/**
394
+ * Try isolating ISAPnP cards at the current read port.
395
+ *
396
+ * @ret \>0		Number of ISAPnP cards found
397
+ * @ret 0		There are no ISAPnP cards in the system
398
+ * @ret \<0		A conflict was detected; try a new read port
399
+ * @err None
307
  *
400
  *
308
  * The state diagram on page 18 (PDF page 24) of the PnP ISA spec
401
  * The state diagram on page 18 (PDF page 24) of the PnP ISA spec
309
  * gives the best overview of what happens here.
402
  * gives the best overview of what happens here.
429
 	return csn;
522
 	return csn;
430
 }
523
 }
431
 
524
 
432
-/*
433
- * Isolate all ISAPnP cards, locating a valid read port in the process.
525
+/**
526
+ * Find a valid read port and isolate all ISAPnP cards.
434
  *
527
  *
435
  */
528
  */
436
 static void isapnp_isolate ( void ) {
529
 static void isapnp_isolate ( void ) {
450
 	}
543
 	}
451
 }
544
 }
452
 
545
 
453
-/*
454
- * Increment a bus_loc structure to the next possible ISAPnP location.
455
- * Leave the structure zeroed and return 0 if there are no more valid
456
- * locations.
546
+/**
547
+ * Increment a @c bus_loc structure to the next possible ISAPnP
548
+ * location.
549
+ *
550
+ * @v bus_loc		Bus location
551
+ * @ret True		@c bus_loc contains a valid ISAPnP location
552
+ * @ret False		There are no more valid ISAPnP locations
553
+ * @err None
554
+ *
555
+ * If there are no more valid locations, the @c bus_loc structure will
556
+ * be zeroed.
457
  *
557
  *
458
  */
558
  */
459
 static int isapnp_next_location ( struct bus_loc *bus_loc ) {
559
 static int isapnp_next_location ( struct bus_loc *bus_loc ) {
471
 	return ( ++isapnp_loc->logdev ? 1 : ++isapnp_loc->csn );
571
 	return ( ++isapnp_loc->logdev ? 1 : ++isapnp_loc->csn );
472
 }
572
 }
473
 
573
 
474
-/*
475
- * Fill in parameters for an ISAPnP device based on CSN
574
+/**
575
+ * Fill in parameters for an ISAPnP device based on CSN.
476
  *
576
  *
477
- * Return 1 if device present, 0 otherwise
577
+ * @v bus_dev		Bus device to be filled in
578
+ * @v bus_loc		Bus location as filled in by isapnp_next_location()
579
+ * @ret True		A device is present at this location
580
+ * @ret False		No device is present at this location
581
+ * @err None
478
  *
582
  *
479
  */
583
  */
480
 static int isapnp_fill_device ( struct bus_dev *bus_dev,
584
 static int isapnp_fill_device ( struct bus_dev *bus_dev,
566
 	return 1;
670
 	return 1;
567
 }
671
 }
568
 
672
 
569
-/*
673
+/**
570
  * Test whether or not a driver is capable of driving the device.
674
  * Test whether or not a driver is capable of driving the device.
571
  *
675
  *
676
+ * @v bus_dev		Bus device as filled in by isapnp_fill_device()
677
+ * @v device_driver	Device driver
678
+ * @ret True		Driver is capable of driving this device
679
+ * @ret False		Driver is not capable of driving this device
680
+ * @err None
681
+ *
572
  */
682
  */
573
 static int isapnp_check_driver ( struct bus_dev *bus_dev,
683
 static int isapnp_check_driver ( struct bus_dev *bus_dev,
574
 				 struct device_driver *device_driver ) {
684
 				 struct device_driver *device_driver ) {
598
 	return 0;
708
 	return 0;
599
 }
709
 }
600
 
710
 
601
-/*
602
- * Describe an ISAPnP device
711
+/**
712
+ * Describe an ISAPnP device.
713
+ *
714
+ * @v bus_dev		Bus device as filled in by isapnp_fill_device()
715
+ * @ret string		Printable string describing the device
716
+ * @err None
717
+ *
718
+ * The string returned by isapnp_describe_device() is valid only until
719
+ * the next call to isapnp_describe_device().
603
  *
720
  *
604
  */
721
  */
605
 static char * isapnp_describe_device ( struct bus_dev *bus_dev ) {
722
 static char * isapnp_describe_device ( struct bus_dev *bus_dev ) {
611
 	return isapnp_description;
728
 	return isapnp_description;
612
 }
729
 }
613
 
730
 
614
-/*
615
- * Name an ISAPnP device
731
+/**
732
+ * Name an ISAPnP device.
733
+ *
734
+ * @v bus_dev		Bus device as filled in by isapnp_fill_device()
735
+ * @ret string		Printable string naming the device
736
+ * @err None
737
+ *
738
+ * The string returned by isapnp_name_device() is valid only until the
739
+ * next call to isapnp_name_device().
616
  *
740
  *
617
  */
741
  */
618
 static const char * isapnp_name_device ( struct bus_dev *bus_dev ) {
742
 static const char * isapnp_name_device ( struct bus_dev *bus_dev ) {
634
 	.name_device		= isapnp_name_device,
758
 	.name_device		= isapnp_name_device,
635
 };
759
 };
636
 
760
 
637
-/*
638
- * Activate or deactivate an ISAPnP device
761
+/**
762
+ * Activate or deactivate an ISAPnP device.
763
+ *
764
+ * @v isapnp		ISAPnP device
765
+ * @v activation	True to enable, False to disable the device
766
+ * @ret None
767
+ * @err None
639
  *
768
  *
640
  * This routine simply activates the device in its current
769
  * This routine simply activates the device in its current
641
- * configuration.  It does not attempt any kind of resource
642
- * arbitration.
770
+ * configuration, or deactivates the device.  It does not attempt any
771
+ * kind of resource arbitration.
643
  *
772
  *
644
  */
773
  */
645
 void isapnp_device_activation ( struct isapnp_device *isapnp,
774
 void isapnp_device_activation ( struct isapnp_device *isapnp,
662
 	      isapnp->csn, isapnp->logdev );
791
 	      isapnp->csn, isapnp->logdev );
663
 }
792
 }
664
 
793
 
665
-/*
666
- * Fill in a nic structure
794
+/**
795
+ * Fill in a nic structure.
796
+ *
797
+ * @v nic		NIC structure to be filled in
798
+ * @v isapnp		ISAPnP device
799
+ * @ret None
800
+ * @err None
801
+ *
802
+ * This fills in generic NIC parameters (e.g. I/O address and IRQ
803
+ * number) that can be determined directly from the ISAPnP device,
804
+ * without any driver-specific knowledge.
667
  *
805
  *
668
  */
806
  */
669
 void isapnp_fill_nic ( struct nic *nic, struct isapnp_device *isapnp ) {
807
 void isapnp_fill_nic ( struct nic *nic, struct isapnp_device *isapnp ) {

Loading…
Cancelar
Guardar