Sfoglia il codice sorgente

Doxygenation

tags/v0.9.3
Michael Brown 19 anni fa
parent
commit
f88c0d42d5
1 ha cambiato i file con 196 aggiunte e 58 eliminazioni
  1. 196
    58
      src/drivers/bus/isapnp.c

+ 196
- 58
src/drivers/bus/isapnp.c Vedi File

@@ -33,16 +33,18 @@
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 49
  * However, we shouldn't make scanning the ISAPnP bus an INIT_FN(),
48 50
  * because even ISAPnP probing can still screw up other devices on the
@@ -50,18 +52,30 @@
50 52
  * an ISAPnP device.
51 53
  *
52 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 73
 uint16_t isapnp_read_port;
60 74
 
61
-/*
75
+/**
62 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 79
  * the PnP BIOS instead.  We therefore set this only when we first try
66 80
  * to Wake[CSN] a device and find that there's nothing there.  Page 16
67 81
  * (PDF page 22) of the ISAPnP spec states that "Valid Card Select
@@ -116,22 +130,56 @@ static inline uint16_t isapnp_read_word ( uint8_t address ) {
116 130
 		 + isapnp_read_byte ( address + 1 ) );
117 131
 }
118 132
 
133
+/** Inform cards of a new read port address */
119 134
 static inline void isapnp_set_read_port ( void ) {
120 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 145
 static inline void isapnp_serialisolation ( void ) {
124 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 156
 static inline void isapnp_wait_for_key ( void ) {
128 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 167
 static inline void isapnp_reset_csn ( void ) {
132 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 183
 static inline void isapnp_wake ( uint8_t csn ) {
136 184
 	isapnp_write_byte ( ISAPNP_WAKE, csn );
137 185
 }
@@ -144,6 +192,19 @@ static inline uint8_t isapnp_read_status ( void ) {
144 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 208
 static inline void isapnp_write_csn ( uint8_t csn ) {
148 209
 	isapnp_write_byte ( ISAPNP_CARDSELECTNUMBER, csn );
149 210
 }
@@ -174,12 +235,20 @@ static void isapnp_delay ( void ) {
174 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 254
 static inline uint8_t isapnp_lfsr_next ( uint8_t lfsr, int input_bit ) {
@@ -190,8 +259,11 @@ static inline uint8_t isapnp_lfsr_next ( uint8_t lfsr, int input_bit ) {
190 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 269
 static void isapnp_send_key ( void ) {
@@ -209,8 +281,12 @@ 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 292
 static uint8_t isapnp_checksum ( struct isapnp_identifier *identifier ) {
@@ -248,9 +324,16 @@ static inline uint8_t isapnp_peek_byte ( void ) {
248 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 339
 static void isapnp_peek ( uint8_t *buf, size_t bytes ) {
@@ -265,12 +348,19 @@ 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 366
 static int isapnp_find_tag ( uint8_t wanted_tag, uint8_t *buf ) {
@@ -300,10 +390,13 @@ static int isapnp_find_tag ( uint8_t wanted_tag, uint8_t *buf ) {
300 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 401
  * The state diagram on page 18 (PDF page 24) of the PnP ISA spec
309 402
  * gives the best overview of what happens here.
@@ -429,8 +522,8 @@ static int isapnp_try_isolate ( void ) {
429 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 529
 static void isapnp_isolate ( void ) {
@@ -450,10 +543,17 @@ 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 559
 static int isapnp_next_location ( struct bus_loc *bus_loc ) {
@@ -471,10 +571,14 @@ static int isapnp_next_location ( struct bus_loc *bus_loc ) {
471 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 584
 static int isapnp_fill_device ( struct bus_dev *bus_dev,
@@ -566,9 +670,15 @@ static int isapnp_fill_device ( struct bus_dev *bus_dev,
566 670
 	return 1;
567 671
 }
568 672
 
569
-/*
673
+/**
570 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 683
 static int isapnp_check_driver ( struct bus_dev *bus_dev,
574 684
 				 struct device_driver *device_driver ) {
@@ -598,8 +708,15 @@ static int isapnp_check_driver ( struct bus_dev *bus_dev,
598 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 722
 static char * isapnp_describe_device ( struct bus_dev *bus_dev ) {
@@ -611,8 +728,15 @@ static char * isapnp_describe_device ( struct bus_dev *bus_dev ) {
611 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 742
 static const char * isapnp_name_device ( struct bus_dev *bus_dev ) {
@@ -634,12 +758,17 @@ struct bus_driver isapnp_driver __bus_driver = {
634 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 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 774
 void isapnp_device_activation ( struct isapnp_device *isapnp,
@@ -662,8 +791,17 @@ void isapnp_device_activation ( struct isapnp_device *isapnp,
662 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 807
 void isapnp_fill_nic ( struct nic *nic, struct isapnp_device *isapnp ) {

Loading…
Annulla
Salva