Home

Compaq AA-PWCBD-TE Computer Accessories User Manual

1. break default L10 sc gt lm_media LAN MEDIA UTP case LAN MEDIA UTP 11 WRITE _ACR sc i ACR_10BT sc gt iobase 12 WRITE_CMD sc CMD _WINDOW4 13 i READ MD sc WRITE MD sc i MD_LBE MD JABE 14 break 1 Calls the READ _ACR macro to read the data from the address control register 2 Clears the ACR_BASE the I O base address and the ACR_10B2 Ethernet thin coaxial cable bits 3 Evaluates the value that is stored in the 1m_media member of the el _softc data structure for this device 4 Determines whether 1m media evaluates to LAN MEDIA BNC media mode is thin wire 5 CallsthewWRITE ACR macro to write data tothe address control register The data to be written establishes the Ethernet thin coaxial cable as the media 6 Calls the WRITE CMD macro a second time to write data to the command port register In this call the data that is written to the command port register is CMD _START2 the start 10Base2 command bit 7 Calls the DELAY macro to wait 800 microseconds 8 Determines whether 1m_media evaluates to LAN MEDIA AUI media mode is the Attachment Unit I nterface 9 Calls WRITE AcR to write tothe address control register The data to be written establishes the Ethernet thick coaxial
2. Sets the lm_media_state member of the softc data structure to LAN MEDIA STATE DETERMINED This indicates that the driver has successfully selected a media mode Calls the splimp routine to mask all LAN hardware interrupts Upon successful completion splimp stores an integer value in the s variable This value represents the CPU priority level that existed before the call to splimp Calls the simple _lock routine to assert a lock with exclusive access for the resource that is associated with the el_softc_lock data structure This means that no other kernel thread can gain access to the locked resource until you call simple_unlock to release it Implementing the Autoconfiguration Support Section probe 5 25 5 26 Because simple locks are spin locks simple lock does not return until the lock has been obtained Theel_ softc_lock member of the el_softc data structure points to a simple lock data structure The if_e1 device driver declares this data structure by calling the decl_ simple lock data routine Calls the WRITE _CMD macro to write data to the command port register In this call el autosense thread passes theif el driver s el_softc data structure pointer The data to be written is the statistics disable command cMD_STATDIS Releases the simple lock and resets the IPL Calls the sp1x routine to reset the CPU priority to the
3. Defines the offset for the I O port of the interrupt and status register This register can be set to one or more of the bit values Defining Device Register Offsets 2 1 Defines the interrupt latch bit position Defines the adapter failure bit position Defines the transmit complete bit position Defines the transmit available bit position Defines the receive complete bit position Defines the receive early bit position Defines the interrupt request bit position Oo IN joy B oO N Defines the update statistics bit position o Defines the command in progress bit position 11 Defines the current window number bit position 2 2 Command Port Register Offset Definitions The following code shows the offset definitions for the command port register Bits 0 10 contain optional parameter bits and bits 11 15 contain the command define CMD_PORT oxe 1 define CMD_RESET 0x0 2 define CMD_WINDOWO Ox1 lt lt 11 0x0 3 define CMD_WINDOW1 Ox1 lt lt 11 0x1 4 define CMD_WINDOW2 Ox1l lt lt 11 0x2 5 define CMD_WINDOW3 Ox1l lt lt 11 0x3 6 define CMD _WINDOW4 Ox1l lt lt 11 0
4. if sc gt ctrblk est_overrun Oxffff sc gt ctrblk est_overrun if sc gt debug printf el d Overrun n ifp gt if_unit break case RX_ERT L5 case RX_EOS sc gt ctrblk est_recvfail_bm 4 if sc gt debug printf el d Bad Sized packet n ifp gt if_unit break case RX_ECR 6 sc gt ctrblk est_recvfail_bm 1 if sc gt debug printf el d CRC n ifp gt if_unit break case RX_EAL 7 default sc gt ctrblk est_recvfail_bm 2 if sc gt debug printf el d Alignment n ifp gt if_unit break else if sc gt debug amp amp len 0 8 printf el d Received illegal size packet d n ifp gt if_unit len else if len lt MHLEN 2 4 9 MGETHDR m M_DONTWAIT MT_DATA else MGETHDR m M_DONTWAIT MT_DATA if m MCLGET2 m M_DONTWAIT if m gt m_flags amp M_EXT 0 m_freem m m struct mbuf NULL Sets up a while loop that executes as long as there are complete packets 13 6 Implementing the Interrupt Section Looks for errors Processes the error Processes the overrun error case Processes the runt and oversized error cases Processes the CRC error case Processes the alignment error case N o d gt o N Discards the packet if none of the previou
5. If in autosense mode starts the autosense kernel thread 8 2 17 Starting the Transmit of Pending Packets The following code shows how the el_init locked routine starts transmitting pending packets Because el init locked may have been called as a result of an error or a reset operation it needs to examine its transmit queue for any pending transmit requests If there are any it starts transmitting them if ifp gt if_snd ifq_ head 1 el_start_locked sc ifp return ESUCCESS 2 If there are any pending packets starts transmitting them by calling theel_start_locked routine 2 Returns ESUCCESS tothe calling routine Implementing the Initialization Section 8 11 9 Implementing the Start Section The start section of a network device driver transmits data packets across the network When the network protocol has a data packet to transmit it prepares the packet then calls the start interface for the appropriate network device driver The start interface transmits the packet When the transmission is complete it frees up the buffers that are associated with the packet The if_el device driver implements the following routines in its start section e el start Section 9 1 e el start locked Section 9 2 9 1 Implementing the el_start Routine Theel_ start routineis a jacket routine that performs the following tasks e Sets
6. ifp gt if_oerrors 1 ifp gt if_collisions 2 if sc gt ctrblk est_sendfail Oxffff sc gt ctrblk est_sendfail sc gt ctrblk est_sendfail_bm 1 2 WRITE TXS sc status WRITE _CMD sc CMD_TXENA else Increments the output errors because the excessive data collisions status means that the transmit failed Indicates excessive collisions N 13 3 4 Writing to the Status Register to Obtain the Next Value The following code shows how the el_tint routine writes to the status register to obtain the next value WRITE_TXS sc status 1 status READ TXS sc sc gt txfree READ TXF sc 2 if sc gt debug if count lt 0 printf elsd Transmit in INFINITE loop 04X n ifp gt if_unit status Writes to the transmit status register to clear the current status in preparation for reading the status for the next transmit completion if any Implementing the Interrupt Section 13 11 N Updates the softc data structure with the amount of space that is available in the transmit FIFO 13 3 5 Queuing Other Transmits The following code shows how the el_tint routine clears the output active flag to permit other transmits to be queued to the device ifp gt if_flags amp IFF_OACTIVE 13 4 Implementing the el_error Routine Theif el driver s el error routine implements the i
7. ifp gt if_affinity NETALLCPU 1 ifp gt lk_softc amp sc gt el_softc_lock 2 simple _lock_setup amp sc gt el_softc_lock el_lock_info 3 Sets the if affinity member of the ifnet data structure for this device to the constant NETALLCPU The if affinity member specifies which CPU torun on You can set this member to one of the following constants defined in if h NETMASTERCPU Specifies that you want to funnel the network device driver because you have not made it symmetric multiprocessor SMP safe This means that the network driver is forced to execute on a single the master CPU This setting is not recommended You are encouraged to make your driver SMP safe NETALLCPU Specifies that you do not want to funnel the network device driver because you have made it SMP safe This means that the network driver can execute on multiple CPUs You make a network device driver SMP safe by using the simple or complex lock mechanism in all critical sections of the driver The if_el driver uses the simple lock mechanism and is therefore SMP safe Sets the 1k_softc member of the ifnet data structure for this device tothe address of the el_softc_lock Both theif el driver andthe network software above the driver use this lock whenever modifications are made to the shared members of the ifnet data structure Make sure to supply a lock for the shared portion of the ifnet structure also Calls the simple
8. 12 7 Setting the Local MAC Address SIOCSPHYSADDR ioctl Command The following code shows how the el_ioct1 routine implements the SIOCSPHYSADDR ioctl command to set the local MAC address case SIOCSPHYSADDR 1 bcopy ifr gt ifr_addr sa_data sc gt is_addr 6 2 pfilt_newaddress sc gt is_ed ess_enetunit sc gt is_addr 3 if ifp gt if_flags amp IFF_RUNNING 4 el_reset_locked sc ifp unit simple unlock amp sc gt el_softc_lock L5 splx s 6 lock_on 0 7 if struct arpcom ifp gt ac_flag amp AC_IPUP 8 rearpwhohas struct arpcom ifp if_sphyaddr ifp ifr L9 break 1 Determines whether the cmd argument is SLTOCSPHYSADDR ioctl 2 Copies the new MAC address tothe ifnet data structure 3 Callsthe pfilt newaddress routine to copy the new address to the packet filter Implementing the ioctl Section 12 5 4 If the 3Com 3C5x9 device is running calls theel_reset_locked routine to restart the network interface with the new address 5 Callsthe simple unlock routine to release the simple lock for the resource that is associated with el_softc_lock 6 Calls the sp1x routine to reset the CPU priority to the level that the s variable specifies 7 Sets the Lock_on variable to 0 false which indicates that the simple loc
9. gt regC el_wait sc c gt regE gt data gt reg6 gt regA gt regC gt regA va va va va va Constructs driver specific macros to read from and write to the 3Com 3C5x9 device s CSRs The first argument to these macros specifies an I O handle that references a device register or memory that is located in bus address space either 1 O space or memory space You can perform standard C mathematical operations addition and subtraction only on the I O handle The READ CCR WRITE_CCR and the other macros construct the first argument by referencing the I O handle that is defined in the el_softc data structure 1 8 Network Device Driver Environment The second argument to the WRITE_CcR and the other write macros specifies the data to be written to the device register in bus address space These write macros construct the second argument by referencing the val variable For the if _e1 driver this data is typically one of the device register offsets that is defined in the if elreg h file The read and write driver specific macros call the mb kernel routine to perform a memory barrier The mb kernel routine ensures that the read or write operation is issued before the CPU executes any subsequent code See Section 7 5 of the Tru64 UNIX Writing Device Drivers manual for more information about the mb routine and when to use it Table 1 1 provides information on th
10. if ifc gt ifc_auto_sense LAN AUTOSENSE ENABLE amp amp 4 ifc gt ifc_media type 1 status EINVAL break Implementing the ioctl Section 12 11 if ifc gt ifc_auto_sense 1 5 if ifc gt ifc_auto_sense LAN AUTOSENSE ENABLE amp amp sc gt 1lm_media_mode LAN MODE AUTOSENSE sc gt lm_media_mode LAN MODE AUTOSENSE need_reset j else if ifc gt ifc_auto_sense LAN AUTOSENSE DISABLE amp amp sc gt 1lm_media_mode LAN MODE AUTOSENSE sc gt lm_media_mode sc gt lm media 6 need_reset if ifc gt ifc_media_type 1 L7 switch ifc gt ifc_media_type L8 case LAN MEDIA UTP case LAN MEDIA AUI case LAN MEDIA BNC if ifc gt ifc_media_type sc gt lm_media 9 need_reset sc gt lm_media_mode sc gt lm media ifc gt ifc_media_type break default status EINVAL break if need_reset amp amp ifp gt if_flags amp IFF_RUNNING 10 el_reset_locked sc ifp unit break default 11 status EINVAL 1 Determines whether the cmd argument is SIOCIFSETCHAR 2 Assumes no device reset is necessary 3 If the LAN speed passed is anything other than 10 1 means no change fails the request 4 Examines the media mode settings If the ioct1 request specifies both autosense enable and an explicit media setti
11. 10 11 12 9 2 3 Transmitting the Buffer 0cccecee cece eee ee eee ea eee 9 2 4 Accounting for Outgoing Bytes c cesses eee e eee ees 9 2 5 Updating Counters Freeing the Transmit Buffer and Marking the Output Process as Active ccceeeeeeeees 9 2 6 Indicating When to Start the Watchdog Routine Implementing a Watchdog Section 10 1 Setting the IPL and Obtaining the Simple Lock 10 2 Incrementing the Transmit Timeout Counter and Resetting ENGINES E oun A cet aeados shew ek 10 3 Releasing the Simple Lock and Resetting the IPL Implementing the Reset Section 11 1 Implementing the el_reset Routine eee eee eee 11 2 Implementing the el_reset_locked Routine eee Implementing the ioctl Section 12 1 Setting Up the el_ioctl Routine cece eee eee eee 12 2 Determining Whether the User Has Removed the PCMCIA Card fromthe Slot rreraino aan e a Pen ne eE aA a 12 3 Setting the IPL and Obtaining the Simple Lock 12 4 Enabling Loopback Mode SIOCENABLBACK ioctl Command aeea a ani a e A a dnc a aada 12 5 Disabling Loopback Mode SIOCDISABLBACK ioctl Command tirare ea A E A aE AA ri TA aiia 12 6 Reading Current and Default MAC Addresses SIOCRPHYSADDR ioctl Command ccce cece eee ee eee 12 7 Setting the Local MAC Address SIOCSPHYSADDR ioctl Command aa aa a siete aati ohGes Pineal aces ded
12. e Selects memory mapping Section 8 2 7 e Resets the transmitter and receiver a second time Section 8 2 8 e Sets theLAN address Section 8 2 9 e Processes special flags Section 8 2 10 e Sets the debug flag Section 8 2 11 e Enables TX and RX Section 8 2 12 e Enables interrupts Section 8 2 13 e Sets the operational window Section 8 2 14 e Marks the device as running Section 8 2 15 e Starts the autosense kernel thread Section 8 2 16 e Starts transmitting pending packets Section 8 2 17 8 2 1 Resetting the Transmitter and Receiver The following code shows how the el_ init locked routine resets the transmitter and receiver This task is specific to the 3Com 3C5x9 device Make sure that you perform similar initialization tasks for the hardware device that your network driver controls static int el init _locked struct el_softc sc struct ifnet ifp int unit register struct controller ctlr el_info unit int i WRITE _CMD sc CMD TXRESET 1 WRITE _CMD sc CMD _RXRESET 2 Calls the WRITE _CMD macro to write data to the command port register In this call el init locked passes the if_e1 driver sel softc data structure pointer The data to be written is the transmit TX reset command CMD_TXRESET 2 Calls the WRITE_CMD macro a second time to write data to the command port register In this call the data to be written to the command port register is
13. ensures that all other function pointers are set before the if output function pointer is set This order is necessary because the if _e1 device can be unattached and later attached again Sets the if _ flags member of the ifnet data structure for this device to the bitwise inclusive OR of the following status bits that are defined in the if h file IFF BROADCAST Signifies that the network interface supports broadcasting and that the associated broadcast address is valid IFF_MULTICAST Signifies that the network interface supports multicast IFF_NOTRAILERS Signifies that the transmission avoids the use of trailers The term trailers refers to the IP trailer encapsulation protocol which is obsolete IFF_SIMPLEX Signifies that the interface cannot identify its own transmissions An mb memory barrier precedes the setting of the if flags member All the function pointers must be initialized before the if flags field is set in case theif el device has been unattached and then attached again Sets the if timer member of the ifnet data structure for this device to the value 0 zero This is the number of seconds to wait until the driver s watchdog interface is called Setting the if_timer member to O0 zero disables the timer Sets the if sysid_ type member of the ifnet data structure for this device to the value 0 zero This optional member specifies a unique number that identifies the bus adapter hardware to the netwo
14. ether header The media header structure for Ethernet related media The if_ether h file defines the ether header structure fddi_header The media header structure for FDDI related media The if fddi h file defines the fddi_header structure trn_header The media header structure for Token Ring related media The if _trn h file defines the trn_header structure 6 3 Setting Up the Media The following code shows how the el_attach routine sets up media related information sc gt is_ac ac_bcastaddr u_char etherbroadcastaddr 1 sc gt is_ac ac_arphrd ARPHRD ETHER 2 ifp gt if_mtu ETHERMTU 3 ifp gt if_mediamtu ETHERMTU 4 ifp gt if_type IFT_ETHER L5 struct arpcom ifp gt ac_flag 0 6 sin struct sockaddr_in amp ifp gt if_addr 7 sin gt sin_family AF_INET 8 Sets the ac_bcastaddr member of the softc data structure for this device to the Ethernet broadcast address The system stores the Ethernet broadcast address in the etherbroadcastaddr character array Tru64 UNIX defines the etherbroadcastaddr character array inthe if ether h file Thename is_ac is an alternate name for the ess_ac member of the ether driver data structure The ess_ac member is referred to as the Ethernet common part and is actually an instance of the arpcom data structure Sets the ac_arphrd memb
15. viii Contents 12 11 12 13 13 1 13 2 13 2 13 3 13 3 13 4 13 4 13 4 13 5 13 5 13 5 13 6 13 7 13 8 13 9 13 10 13 10 13 10 13 11 13 11 13 12 13 12 2 4 Window 4 Diagnostic Registers ceceeeee cece eee e eae 2 11 3 1 Typical softc Data Structure cece eeeeee eee eee eee eae 3 2 3 2 Mapping Alternate Names ar suited ave Ae chen Monae N E aan aaah 3 4 Tables 1 1 Driver Specific MACrOS cc cceecee eee ee eee eee teeta eee 1 9 12 1 Network ioctl Commands ccc cece eee eee eee teed 12 1 12 2 Network Interface Counter Types ceeeee eee eee teed 12 9 Contents ix About This Manual This manual discusses how to write network device drivers for computer systems that run the Compaq Tru64 UNIX operating system Audience This manual is intended for systems engineers who e Usestandard library routines to develop programs in the C language e Know the Bourne shell or some other shell that is based on the UNIX operating system e Understand basic Tru64 UNIX concepts such as kernel shell process configuration and autoconfiguration e Understand how to use the Tru64 UNIX programming tools compilers and debuggers e Develop programs in an environment that involves dynamic memory allocation linked list data structures and multitasking e Understand the hardware device for which the driver is being written e Understand the basics of the CPU hardware arch
16. ASI_IAS BOT ASI_IAS NON AST _PAR_35 ASI PAR_13 ASI PAR 11 ASI_RS AST _RW 2 8 Defining Device Register Offsets Activates ISA bus contention Activates ISA bus PNP Activates ISA bus contention and PNP Indicates neither ISA nor PNP activation Uses the RAM partition 3 TX to 5 RX 3 5 Uses the RAM partition 1 TX to 3 RX 1 3 Uses the RAM partition 1 TX to 1 RX 1 1 Indicates the RAM speed Indicates the RAM width which will always be 0 to 8 bits ASI_RSIZE8 Indicates a RAM size of 8 kilobytes the default ASI_RSIZE32 Indicates a RAM size of 32 kilobytes 2 5 Window 1 Operational Register Offset Definitions The window 1 operational registers include such registers as the receive status the transmit status and the request interrupt registers as shown in Figure 2 3 Figure 2 3 Window 1 Operational Registers Register Receive Status Register W1_RXSTAT Transmit Status Register W1_TXSTAT Request Interrupt After Transmit Completion Register TXINT Receive Data Register W1_RXDATA Transmit Data Register W1_TXDATA Free Transmit Bytes Register W1_FREETX ZK 1269U AI The following code shows the offset definitions for the window 1 operational registers define W1_RXSTAT oxs 1 enum wl_rxstat RX_IC 0x8000 RX _ER 0x4000 RX_EM 0x3800 RX EOR 0x0000 RX_ERT 0x1800 RX _ EAL 0x2000 RX _ECR 0x2800 RX _EOS 0x0800 RX_BYTES 0x7ff N i define W1_TXSTAT
17. ND_LOW 0x0001 Defines the offset for the media type and status register Defining Device Register Offsets 2 11 2 Defines an enumerated data type called w4_ media Theif_el device driver can assign one of the following values to W4_ MEDIA the media type and status register MD_TPE MD_COAXE MD_RES1 MD_SQE MD_VLB MD_PRD MD_JAB MD_UNSQ MD_LBE MD _JABE MD_CS MD_COLL MD_SQEE MD_NCRC Indicates that 10BaseT cable is enabled Indicates that 10Base2 cable is enabled Reserved Indicates that SQE is present Indicates that a valid link beat was detected Indicates that polarity reversal was detected Indicates that jabber was detected Indicates unsequelch Indicates that link beat was enabled Indicates that jabber was enabled Indicates that carrier sense was detected Indicates that collisions occurred Indicates that SQE stats were enabled Indicates that the CRC strip was disabled 3 Defines the offset for the network diagnostic port register 4 Defines an enumerated data type called w4_net Theif_el device driver can assign one of the following values to W4_ NET the network diagnostic port register ND_EXT ND_ENDEC ND_ECL ND_LOOP ND_TXE ND_RXE ND_TXB ND_TXRR ND_STATE ND_REV ND_LOW Indicates external loopback Indicates encode decode EN DEC loopback Indicates Ethernet controller loopback Indicat
18. WRITE_CMD sc CMD _WINDOW3 i sc gt eeprom icw amp ASI_RS ASI_RS ASI_RSIZE8 ASI_RSIZE32 ASI_PAR_35 ASI_PAR_13 ASI_PAR 11 i ASI_PAR_11 ASI_RSIZE32 WRITE _DATA sc i If the if e1 device driver operates on the PCMCIA bus performs a read operation and a number of write operations to select the memory mapping 8 2 8 Resetting the Transmitter and Receiver Again The following code shows how the el_ init locked routine resets the transmitter and receiver a second time This task is specific to the 3Com 3C5x9 device Make sure that you perform similar initialization tasks for the hardware device that your network driver controls Implementing the Initialization Section 8 7 WRITE _CMD sc CMD TXRESET 1 WRITE _CMD sc CMD _RXRESET 2 Calls the WRITE_CMD macro to write data to the command port register The data to be written is the transmit TX reset command CMD_TXRESET Calls the WRITE _CMD macro to write data to the command port register In this call the data to be written is the receive RX reset command CMD_RXRESET 8 2 9 Setting the LAN Address The following code shows how the el_ init locked routine sets the LAN address This task is specific to the 3Com 3C5x9 device You may want to perform similar initialization tasks for the hardware device that your network driver controls WRITE _CMD sc CMD WINDOW2
19. 0 while prev_tint sc gt tint amp amp 1 prev_tmo sc gt xmit_tmo amp amp waitt lt 4 assert wait vm_offset_t amp wait_flag TRUE thread_set_timeout 1 hz L2 thread_block 1 Waits until the transmit makes it out a timeout occurs or 4 seconds pass 2 Sets the timer and puts the current thread to sleep To use a timer thread _set_ timeout must be called between an assert wait anda thread _block 5 3 13 Testing for Loss of Carrier The following code shows how the el_autosense thread routine tests for loss of carrier link _beat 0 1 switch sc gt lm media case LAN MEDIA UTP s splimp simple lock amp sc gt el_softc_lock WRITE _CMD sc CMD _WINDOW4 i READ MD sc if i amp MD_VLB 0 ink_beat 1 WRITE _CMD sc CMD _WINDOW1 simple unlock amp sc gt el_softc_lock splx s case LAN MEDIA BNC case LAN MEDIA AUI s splimp simple lock amp sc gt el_softc_lock WRITE _CMD sc CMD _WINDOW6 WRITE _CMD sc CMD _STATSDIS i READ BUS D8 sc gt basereg if i 0 wait 100 if sc gt debug printf el d autosense s carrier loss n ifp gt if_unit lan_media_strings_10 sc gt lm_media WRITE _CMD sc CMD_STATSENA Implementing the Autoconfiguration Support Section probe 5 23 WRITE _CMD sc CMD _WINDOW1 simple unlock amp sc gt el_softc_lock splx s brea
20. 1 i sc gt is_addr 1 lt lt 8 sc gt is_addr 0 WRITE AD1 sc i i sc gt is_addr 3 lt lt 8 sc gt is_addr 2 WRITE AD2 sc i i sc gt is_addr 5 lt lt 8 sc gt is_addr 4 WRITE _AD3 sc i lan_set_attribute sc gt ehm current_val NET MAC NDX N ether_sprintf sc gt is_addr 2 Performs several write operations to set the LAN address Sets the LAN MAC address attribute for EHM support 8 2 10 Processing Special Flags 8 8 The spec that your if el i if if following code shows how the el_init locked routine processes ial flags This task is specific to the 3Com 3C5x9 device Make sure you perform similar initialization tasks for the hardware device that network driver controls ifp gt if_flags amp IFF LOOPBACK 1 WRITE _CMD sc CMD _WINDOW4 i READ ND sc WRITE ND sc ND LOOP i lan_set_attribute sc gt ehm current_val NET_LOOP_NDX void 1 2 se lan_set_attribute sc gt ehm current_val NET_LOOP_NDX void 0 j RF_IND RF_BRD 3 ifp gt if_flags amp IFF_ALLMULTI sc gt is_multi lan_nmulti 4 i RF_GRP ifp gt if_flags amp IFF_PROMISC 5 i RF_PRM lan_set_attribute sc gt ehm current_val NET_PROMISC_NDX void 1 L6 Implementing the Initialization Section
21. 8 1 5 Releasing the Simple Lock and Resetting the IPL The following code shows how the el_init routine releases the simple lock and resets the IPL All network device drivers that do not use the simple lock mechanism must reset the IPL All network device drivers that use the simple lock mechanism must reset the IPL after releasing the simple lock simple unlock amp sc gt el_softc_lock 1 splx s 2 Calls the simple unlock routine to release the simple lock Calls the sp1x routine to reset the CPU priority to the level that is stored in the s variable N 8 1 6 Returning the Status from the el_init_locked Routine The following code shows how the el_init routine returns status from el_init_locked return i 1 1 Exits and returns the status from el init _locked 8 2 Implementing the el_init_locked Routine Theel init locked routine initializes the network interface It is called by the if el devicedriver s el init andel reset locked routines Theel_init_locked routine performs the following tasks e Resets the transmitter and receiver Section 8 2 1 e Clears interrupts Section 8 2 2 e Starts the device Section 8 2 3 e Ensures that the 10Base2 transceiver is off Section 8 2 4 e Sets the LAN media Section 8 2 5 Implementing the Initialization Section 8 3 e Sets theLAN media type attribute Section 8 2 6
22. Defines the window selector for commands that are used to set up the device 4 Defines the window selector for commands that control the operation of the device 5 Defines the window selector for specifying the hardware address of the device 6 Defines the window selector for the device s first in first out F IF O buffer 7 Defines the window selector for commands that are used for diagnostic purposes 8 Defines a second window selector for commands that are used for diagnostic purposes 9 Defines the window selector for commands that are related to gathering device statistics 10 Defines the start 1OBase2 Ethernet cable command 11 Defines the receive RX disable command 12 Defines the receive RX enable command 13 Defines the receive RX reset command 14 Defines the receive RX discard top packet command 15 Defines the transmit TX enable command 16 Defines the transmit TX disable command 17 Defines the transmit TX reset command 18 Defines the request interrupt command 19 Defines the acknowledge interrupt command 20 Defines the set interrupt mask command 21 Defines the clear interrupt command 22 Defines the receive RX filter command Defining Device Register Offsets 2 3 23 24 25 26 27 28 29 30 31 32 33 Defines an enumerated data type called rx_filter Theif_el device driver can assi
23. ceeeee eee eee 7 4 7 9 Terminating the Simple LOCK sssssssssessesersersesrerseresrss 7 4 Contents v 7 10 7 11 Unregistering the Card from the Hardware M anagement Database sieer ni eae ea here aaa Rend Edw heehee vr Freeing RESOUrCES cccceecceeeeeeeeeeeeeeeeeeeeeseeneeesenneeres 8 Implementing the Initialization Section 8 1 8 1 1 8 1 2 8 1 3 8 1 4 8 1 5 8 1 6 8 2 8 2 1 8 2 2 8 2 3 8 2 4 8 2 5 8 2 6 8 2 7 8 2 8 8 2 9 8 2 10 8 2 11 8 2 12 8 2 13 8 2 14 8 2 15 8 2 16 8 2 17 Implementing the el_ init Routine cece eee eee eee eee Setting Up the el_init Routine ccc cece Determining Whether the PCMCIA Card Is Present Setting the IPL and Obtaining the Simple Lock Calling the el_init_locked Routine ce eeeeee eee ee Releasing the Simple Lock and Resetting the IPL Returning the Status from the el_init_locked Routine Implementing the el_init_locked Routine eee Resetting the Transmitter and Receiver 0 eeee Clearing Interrupts cceeeee eect eee e eee teen ene Starting the Device 6 cece eect eect ee ee eee eens Ensuring That the 10Base2 Transceiver Is Off Setting the LAN Media cc cece e eect ee eee eens Setting a LAN Attribute cece eee eee ee Selecting Memory Mapping cecceeee eens eee eens Resetting the Transmitter and R
24. header file 2 1 12 10 driver data structure declaring and initializing 1 7 SIOCSIP MTU ISE command driver interface L210 specifying in ifnet data structure SIOCSMACSPE ED iodtlcommand 6 6 12 11 l dynamic configuration 14 1 2 z Pa een el_probe routine 5 1 E allocating memory for the el_softc data structure 5 6 allocating multiple controller data first time probe operation 5 10 structures 5 16 subsequent probe operations allocating the ether_driver data 5 12 structure 5 7 el_autosense thread routine 5 17 checking the maximum number of el_error routine 13 12 devices 5 4 el init locked routine 8 3 handling first time tasks 5 10 aalling ina init 8 3 initializing bus specific data returning status from 8 3 Structures 5 8 el intr routine 13 1 initializing the el_softc data el_ioctl routine structure 5 8 EEPROM reading and saving Index 2 initializing the enhanced hardware management data structure 5 8 performing bus specific tasks 5 4 registering interrupt handlers 5 15 registering the shutdown routine 5 17 saving controller and el_softc data structure pointers 5 16 setting up 5 2 el_reset routine 11 1 el_reset_locked routine 11 2 el_rint routine 13 5 el_shutdown routine 5 17 el_softc data structure allocating memory for 5 6 array declaration 1 6 saving pointer 5 16 el_start routine 9 1 el_start_locked routine 9 3 calling from el_start 9 2 el_tint routine 13 10 el_watch
25. if ifp gt if_flags amp IFF_RUNNING 2 el_reset_locked sc ifp unit break Determines whether the cmd argument is SIOCSIFFLAGS If the 3Com 3C5x9 device is running calls theel_ reset _locked routine to restart the network interface with the current flag settings N 12 13 Setting the IP MTU SIOCSIPMTU ioctl Command The following code shows how the el_ioct1 routine implements the SIOCSIPMTU ioctl command to set the IP MTU You must implement this task in your network driver to accommodate the IP layer case SIOCSIPMTU 1 bcopy ifr gt ifr_data if ifmtu gt ETHERMTU ifmtu lt IP_MINMTU status EINVAL else ifp gt if_mtu ifmtu lan_set_attribute sc gt ehm current_val NET_MTU_NDX void ifmtu u_char amp ifmtu sizeof u_short 2 break Determines whether the cmd argument is SIOCSIPMTU Compares the passed value to the media s maximum and minimum values If this value is not within the range allowed the driver returns an error Otherwise it sets the if mtu member of the driver s ifnet data structure to the specified IP MTU value Also updates the corresponding hardware attribute in the enhanced hardware management EHM database 12 14 Setting the Media Speed SIOCSMACSPEED ioctl Command The following code shows how the e1_ioct1 routine implements the SIOCSMACSPEED ioct1 command to set the media speed
26. muse lan_build_mclist mclist_buf NET_SZ MCLIST amp sc gt is multi L5 lan_set_attribute sc gt ehm current_val NET_MCLIST_NDX mclist_buf break 1 Determines whether the cmd argument is SIOCADDMULTI 2 If the address is broadcast indicates the presence of another broadcast user If the address is multicast the el ioct1 routine adds the address to the table The EtherLink III family does not support any multicast filtering Either you receive all multicast addresses or you do not receive any The EtherLink II family does special case the broadcast address 3 If the add succeeds and there are no other multicasts enabled increments a counter that indicates that the device needs to be reset 4 If the deviceis running and multicasts and broadcasts have not already been enabled enables them 5 Builds a text string that lists all currently active multicast addresses and sets this list as an enhanced hardware management EHM attribute for this network device 12 9 Deleting the Device from a Multicast Group SIOCDELMULTI ioctl Command The following code shows how the el_ioct1 routine implements the SIOCDELMULTI ioct1 command to delete a multicast address case SIOCDELMULTI 1 need_reset 0 if bemp ifr gt ifr_addr sa_data etherbroadcastaddr 6 0 2 sc gt is_broadcast j else i lan_del_multi amp sc gt is_ multi
27. over the network media Network devices have network device drivers associated with them A network device driver attaches a network subsystem to a network interface prepares the network interface for operation and governs the transmission and reception of network frames over the network interface Examples of network interface types include Ethernet Fiber Distributed Data Interface F DDI and Token Ring Similar to the character and block device drivers that are discussed in Writing Device Drivers a network device driver has the following sections e An include files section Section 1 1 e A declarations section Section 1 2 e A configure section Section 1 3 e An autoconfiguration support section Section 1 4 e An ioctl section Section 1 9 e An interrupt section Section 1 10 Similar to a character device driver a network device driver can also havea reset section Section 1 8 Unlike a character or block device driver a network device driver contains the following network driver specific sections e An initialization section Section 1 5 e A start transmit section Section 1 6 e A watchdog section Section 1 7 e An output section Section 1 11 Figure 1 1 shows the sections that a typical network device driver can contain Network device drivers are not required to have all of these sections and more complex network drivers can have additional sections However all network drivers must have a configure sectio
28. 2 Initializing the Media Address and Media Header Lengths Theel_attach routine sets up the media s address length and header length as follows if sc gt reprobe 1 ctlr gt alive ALV_STATIC 2 ifp gt if_addrlen 6 3 ifp gt if_hdrlen 4 sizeof struct ether header 8 Examines the value of the reprobe member of the driver s softc data structure to determine whether the user has reinserted the PCMCIA card If the card has been reinserted the driver skips to the code in Section 6 10 Because the if _e1 device driver must always be linked into the kernel sets the ALV_STATIC bit If your driver can be dynamically loaded set the ALV_NOSIZER bit instead Sets the if addrlen member of the ifnet data structure for this device to the media address length which in this case is 6 bytes the IEEE standard 48 bit address Sets the if hdrlen member of the ifnet data structure for this device to the media header length The el_attach routine uses the sizeof operator to return the size of the data structure because it can differ from one network type to another In this example the media 6 2 Implementing the Autoconfiguration Support Section attach header length is the size of the ether header data structure plus 8 the size of the maximum LLC header The media headers are represented by the following data structures
29. Starting Up Statistics The following code shows how the el_autosense thread routine starts up statistics s splimp 4 simple lock amp sc gt el_softc_lock WRITE _CMD sc CMD _STATSENA simple unlock amp sc gt el_softc_lock splx s Starts up statistics totest for the loss of the carrier during the transmit operation 5 3 5 Entering the Packet Transmit Loop The following code shows how the el_autosense thread routine enters the packet transmit loop good_xmits passes 0 1 sc gt lm_media_state LAN MEDIA STATE SENSING while good_xmits lt 5 while thread_should_halt sc gt autosense_thread printf el d Autosense thread exiting n ifp gt if_unit s splimp simple lock amp sc gt el_softc_lock WRITE _CMD sc CMD _STATSDIS 5 20 Implementing the Autoconfiguration Support Section probe simple unlock amp sc gt el_softc_lock splx s thread_halt_self j Enters a loop for transmitting a packet and determining if it succeeds A packet must go out twice successfully for media selection to succeed This algorithm probably will not work in all cases 5 3 6 Saving Counters Prior to the Transmit Operation The following code shows how the el_autosense thread routine saves counters prior to the transmit operation prev_tint sc gt tint prev_err ifp gt if_oerrors prev_tmo sc gt xmit_tmo 5 3 7 Alloca
30. Theis if name is an alternate name for the ac_if member of the arpcom data structure The ac_if member is referred to as the network visible interface and is actually the instance of the ifnet data structure for this 3Com 3C5x9 device 5 3 2 Blocking Until Awakened The following code shows how theel_autosense thread routine blocks until awakened while 1 assert_wait vm_offset_t amp sc gt autosense flag TRUE 1 thread_block Waits for some process to indicate when to proceed with the autosense test Implementing the Autoconfiguration Support Section probe 5 19 5 3 3 Testing for the Termination Flag The following code shows how the el_autosense thread routine tests for the termination flag while thread_should_halt sc gt autosense_thread 1 printf el d Autosense thread exiting n ifp gt if_unit thread_halt_self 2 Performs an initial test for the termination flag The termination flag would have been set if another kernel thread had called the thread _terminate routine for the el autosense thread routine 2 The thread halt _self routine performs the work that is associated with a variety of asynchronous traps ASTs for a kernel thread that terminates itself A kernel thread terminates itself by callingthethread_halt_self routine Thethread_halt_self routine does not return to the caller 5 3 4
31. and obtains the simple lock static int el _intr int unit 1 register u_int s volatile u_int status register struct el softo sc el _softc unit register struct ifnet ifp amp sc gt is_if if el_card_out sc return INTR_NOT_SERVICED 2 s splimp L3 simple _ lock amp sc gt el_softc_lock 4 1 Declares an argument that specifies the unit number of the network interface that generated the interrupt 2 Determines whether the card is still in the socket If the card is no longer in the socket then returns the constant INTR_NOT_SERVICED to the kernel interrupt dispatcher 3 Callsthe splimp routine to mask all Ethernet hardware interrupts 4 Callsthesimple lock routine to assert a lock with exclusive access for the resource that is associated with el_softc_lock 13 1 2 Rearming the Next Timeout 13 2 The following code shows how the el_intr routine rearms the next timeout if sc gt polling flag 1 timeout void el_intr void unit 1 hz el_pollint 2 1 Determines whether polling was started by testing the polling flag flag member in the el_softc data structure for this device 2 If the polling process was started calls the timeout routine to rearm the next timeout The timeout routineis called with the following arguments e A pointe
32. attributes 6 9 shutdown routine registering 5 17 simple lock obtaining in el_intr 13 2 in el_ioctl 12 3 in el_start 9 1 in el_watch 10 1 inel_init 8 2 releasing in el_init 8 3 in el_intr 13 4 in el_ioctl 12 13 in el_start 9 2 in el_watch 10 2 setting up 6 5 simple lock data structure declaring 3 10 SIOCADDMULTI ioctl command 12 6 SIOCDELMULTI ioctl command 12 7 Index 6 SIOCDISABLBACK ioctl command 12 4 SIOCE NABLBACK ioctl command 12 4 SIOCIFRE SET ioctl command 12 11 SIOCIFSETCHAR ioctl command 12 11 SIOCRDCTRS ioctl command 12 8 SIOCRDZCTRS ioctl command 12 8 SIOCRPHYSADDR ioctl command 12 5 SIOCSIFADDR ioctl command 12 9 SIOCSIFFLAGS ioctl command 12 10 SIOCSIPMTU ioctl command 12 10 SIOCSMACSPEED ioctl command 12 11 SIOCSPHYSADDR ioctl command 12 5 softc data structure 3 1 start section 1 10 implementing 9 1 static configuration 14 1 statistics starting up 5 20 status register offset definitions 2 1 writing to obtain the next value 13 11 sysconfig h header file 1 4 sysconfigtab file fragment 14 1 T termination flag testing for 5 20 test packet building 5 21 loading into the buffer 5 22 transmitting 5 22 timeout information in el_softc data structure 3 9 rearming the next 13 2 timer clearing 10 2 transmit counting interrupts 13 10 counting timeouts 10 2 discarding all 9 3 freeing buffer 9 7 of pending packets 8 11 p
33. cable as the media 8 6 Implementing the Initialization Section 10 For the default case sets the 1m_media member to LAN MEDIA UTP media mode is unshielded twisted pair cable 11 Determines whether 1m_media evaluates to LAN MEDIA UTP 12 Calls WRITE_ACR to write to the address control register The data to be written establishes the Ethernet unshielded twisted pair cable as the media 13 Calls WRITE cMD to write tothe command port register The data to be written is the window 4 diagnostic command bit cMD_WINDOW4 14 Calls the WRITE MD macro to write data to the media type and status register The data to be written consists of the original data from that register but with the link beat enabled MD_LBE and the jabber enabled MD_JABE bits set 8 2 6 Setting a LAN Attribute The following code shows how theel_init_locked routinesets the LAN media type attribute for enhanced hardware management EHM support lan_set_attribute sc gt ehm current_val NET MEDIA NDX lan_media_strings sc gt lm_media 1 1 Sets the LAN media type attribute for EHM support 8 2 7 Selecting Memory Mapping The following code shows how the el_ init locked routine selects memory mapping This task is specific to the 3Com 3C5x9 device if ctlr gt bus_hd gt bus_type BUS _PCMCIA 4 WRITE_CMD sc CMD WINDOWO i READ _CCR sc if i amp Oxc000 0x8000
34. checksum cw2 Contains a second compatibility word resl1 Reserved icw Contains an internal configuration word swinfo2 Contains secondary software information res Reserved cs2 Contains the second part of the checksum pnp Contains plug and play data Defining Device Register Offsets 2 13 3 Defining the softc Data Structure All network device drivers define a softc data structure to contain the software context of the network device driver and to allow the driver interfaces to share information A softc data structure contains the following information Common information Section 3 1 Enhanced hardware management E H M support Section 3 2 Media state information Section 3 3 Base register definition Section 3 4 Multicast table information Section 3 5 Interrupt handler ID declaration Section 3 6 CSR pointer information Section 3 7 FIFO maintenance information Section 3 8 Bus specific information Section 3 9 Broadcast flag definition Section 3 10 Debug flag definition Section 3 11 Interrupt and timeout statistics Section 3 12 Autosense kernel thread context information Section 3 13 Polling context flag definition Section 3 14 w3_eeprom data structure definition Section 3 15 Simple lock data structure declaration Section 3 16 Figure 3 1 shows a typical softc data structure Defining the softc Data Structure 3 1 Figure 3 1 Typical softc Data Structure Multicast Table Inf
35. driver s probe interface to the media state constant that identifies the state for the media You can set the lan_media member to the same constants that are listed for the lan_media_mode member in item 2 3 4 Defining the Base Register The base register in a network driver s softc data structure is a member that represents the base register of the device The following code shows the declaration of the base register in theif _e1 devicedriver s el _softc data structure Most network device drivers declare a variable to store the device s base register vm_offset_t basereg 1 Declares a base register member and calls it basereg 3 5 Defining Multicast Table Information All multicast address information in a network driver s softc data structure is encapsulated in the lan_multi data structure The following code shows the declaration of the lan_multi data structurein theif el devicedriver s el_softc data structure Most network device drivers declare this data structure in their softc data structure struct lan multi is multi 1 Declares a lan_multi data structure and callsitis multi 3 6 Defining the Interrupt Handler ID The interrupt handler ID in a network driver s softc data structureisa variable that stores the interrupt handler ID that the handler _add routine returns The following code shows the declaration of the interrupt handler ID in the if _e1 devi
36. drivers perform this task ifp gt if_timer 3 L121 Sets the time in seconds for starting the if _e1 driver s watchdog routine called el _watch After the transmit complete interrupt is received the interrupt service routine sets if timer back to zero thereby disabling the watchdog timer 9 8 Implementing the Start Section 10 Implementing a Watchdog Section Network device drivers can take advantage of the watchdog timer The network layer implements this mechanism to ensure that the network device is transmitting data The driver starts the watchdog timer when it sends a transmit request to the device After it receives the transmit completion interrupt the driver stops the timer If the interrupt never happens the timer expires and the driver s watchdog interface is called The watchdog timer is implemented using the if timer member of the device s ifnet data structure The value stored there represents the number of seconds to wait for the transmit to complete Once per second the network layer examines this value If it is O zero then the timer is disabled Otherwise the value is decremented and if it reaches 0 zero the driver s watchdog interface is called The watchdog section of a network device driver is an optional interface but we recommend that all network drivers have one The if_el device driver implements a watchdog routine called el _watch which pe
37. e WRITE _CMD sc CMD FILTER i 7 lse lan_set_attribute sc gt ehm current_val NET_PROMISC_NDX void 0 If loopback mode is requested enables it Sets the LAN loopback attribute for EHM support Selects to receive frames that are sent to both the local address and the broadcast address If the network device receives all multicast packets selects all group addresses If the network device receives all packets destined to all stations selects promiscuous mode Sets the LAN promiscuous mode attribute for EHM support Calls the WRITE _CMD macro to write data to the command port register In this call the data to be written is the set receive RX filter command CMD_FILTER with the appropriate flags set 8 2 11 Setting the Debug Flag 8 2 12 The following code shows how the el_ init locked routine sets the debug flag for turning on debugging on a running system This task is optional if ifp gt if_flags amp IFF_DEBUG 1 el if N Ena sc gt debug se sc gt debug 0 sc gt debug 2 WRITE _CMD sc CMD _WINDOW3 i READ _TXF sc printf el d Transmit FIFO size d n unit i i READ _RXF sc WRITE _CMD sc CMD _WINDOW1 printf el d Receive FIFO size d n unit i Sets debug mode if the IFF_DEBUG bit is set If debugging mode is set print
38. ed if bcmp sc gt eeprom addr ee copy addr 6 3 for i 0 i lt 3 i 4 j sc gt eeprom addr i tmp_addr i 2 j gt gt 8 amp Oxff tmp_addr i 2 1 j amp Oxff if bcmp tmp_addr sc gt is_ addr 6 0 5 for i 0 i lt 3 i L6 j ee_copy addr i tmp_addr i 2 j gt gt 8 amp Oxff tmp_addr i 2 1 j amp Oxff bzero amp ifr sizeof struct ifreq beopy tmp_addr ifr ifr_addr sa_data 6 beopy tmp_addr sc gt is_addr 6 L7 if struct arpcom ifp gt ac_flag amp AC_IPUP 8 rearpwhohas struct arpcom ifp if_sphyaddr ifp amp ifr 9 pfilt_newaddress sc gt is_ed ess_enetunit sc gt is_addr 10 Implementing the Autoconfiguration Support Section probe 5 13 bcopy amp ee_copy amp Sc gt eeprom sizeof struct w3_eeprom 11 1 If this is a multifunction card reads the EEPROM data and saves it in a temporary data structure ee copy If this is a 3Com 3C562 multifunction PC card the EEPROM data is located in the card information data structure 2 If this is not a multifunction PC card the EEPROM data is read directly from the card and saved in the el_sofc data structure 3 Calls the bcmp routine to compare the EEPROM address from the first probe operation to the EEPROM addre
39. had originally been requested by the user 2 Removes the scheduled event from the systems timer queue 3 Sets the polling flag member to 0 false to indicate that polling has stopped 7 8 Unregistering the Shutdown Routine The following code shows how the el_unattach routine unregisters the shutdown routine drvr_register_shutdown el_ shutdown void sc DRVR_UNREGISTER 1 Unregisters the shutdown routine which was registered during the probe operation 7 9 Terminating the Simple Lock The following code shows how the el_unattach routine terminates the softc lock simple lock terminate amp sc gt el_softc_lock 1 Frees up the softc lock 7 4 Implementing the unattach Routine 7 10 Unregistering the Card from the Hardware Management Database The following code shows how the el_unattach routine unregisters the card from the hardware management database lan_ehm_free amp sc gt ehm 1 Frees up any memory allocated for enhanced hardware management and unregisters this card from the hardware management database 7 11 Freeing Resources The following code shows how the el_unattach routine frees data structures and memory that the adapter uses FREE sc M DEVBUF 1 el_softc unit NULL el_info unit NULL el_configured return ESUCCESS Frees all
40. ispcmcia pcmcia_unregister_event_callback card_infop gt socket_vnum CARD_REMOVAL_EVENT caddr_t el_card_remove if_dealloc sc gt is_ed j lan_ehm_free amp sc gt ehm FREE sc M DEVBUF return 0 else 3 ed unsigned short amp sc gt eeprom 5 10 Implementing the Autoconfiguration Support Section probe for i 0 i lt sizeof struct w3_eeprom 2 i WRITE _ECR sc ECR_READ i DELAY 1000 ed READ EDR sc ed for i 0 i lt 3 i 4 j sc gt eeprom addr i sc gt is_addr i 2 j gt gt 8 amp Oxff sc gt is_addr i 2 1 j amp Oxff sc gt lm_media_mode LAN MODE AUTOSENSE 5 sc gt lm_media_state LAN MEDIA STATE SENSING 6 sc gt lm_media LAN MEDIA UTP 7 sc gt autosense thread kernel thread_w_arg first_task 8 el _autosense thread void sc if sc gt autosense thread NULL 9 printf el d Can t create autosense thread n unit if sc gt ispcmcia 10 pemcia_unregister_event_callback card_infop gt socket_vnum CARD_REMOVAL_EVENT caddr_t el_card_remove if_dealloc sc gt is_ed j 11 lan_ehm_free amp sc gt ehm 12 FREE sc M DEVBUF 13 return 0 14 Determines whether the device has already been pr
41. level that is stored in the s variable Implementing the Autoconfiguration Support Section probe 6 Implementing the Autoconfiguration Support Section attach The autoconfiguration support section implements a network device driver s attach interface A network device driver s attach interface establishes communication with the device The interface initializes the pointer to the ifnet data structure and attaches the network interface to the packet filter The bus configuration code calls the driver s attach interface The if el device driver implements an attach routine called el_attach Theel attach routine performs the following tasks e Initializes the media address and media header lengths Section 6 2 e Sets up the media Section 6 3 e Initializes simple lock information Section 6 4 e Prints a success message Section 6 5 e Specifies the network driver interfaces Section 6 6 e Sets the baud rate Section 6 7 e Attaches to the packet filter and the network layer Section 6 8 e Sets network attributes and registers the adapter Section 6 9 e Handles reinsertion operations Section 6 10 e Enables the interrupt handler Section 6 11 e Starts the polling process Section 6 12 6 1 Setting Up the el_attach Routine The following code shows how to set up the el_attach routine static int el _attach struct controller ctlr 1 register int unit ctlr s g
42. lock init routine to initialize the simple lock structure called el _softc_ lock You need to initialize the simple lock structure only once Implementing the Autoconfiguration Support Section attach 6 5 6 5 Printing a Success Message The following code shows how the el_attach routine prints a success message printf el d s hardware address s n unit ifp gt if_version ether _sprintf sc gt is_addr 1 1 Calls the printf routine to display the following information message on the console terminal e Thecontroller number that is stored in the unit variable e The version of the network interface that is stored in the if version member of the ifnet data structure pointer e The hardware address that is accessed through the is_addr member of the el_softc data structure for this device Theif_ el device driver maps the ac_enaddr member of the arpcom data structure to the alternate name is_addr The argument list that is passed to printf contains a call tothe ether sprintf routine Theether_ sprintf routine converts an Ethernet address to a printable ASCII string representation Make sure that your driver prints a similar message during its attach routine 6 6 Specifying the Network Driver Interfaces The following code shows how the el_attach routine specifies the network driver interfaces for the if _e1 driver ifp gt if_ioctl el_ioctl 1 ifp gt if_watchd
43. lock is already held then another thread is executing somewhere in the driver and is either currently servicing the transmit request queue or will service it soon Therefore the transmit request that was put on the send queue prior to calling the start interface will be handled shortly In this case the code does not need to wait for the lock because someone else will do the transmit and can return to the caller The argument to simple lock _try is a pointer toa simple lock data structure The if _e1 device driver declares the simple lock data structure by calling the decl_ simple lock data routine and it stores a pointer to this data structure in the el_softc data structure If the simple lock try routine fails to assert the simple lock calls the sp1x routine to reset the CPU priority to the level that the s variable specifies then returns Otherwise the simple lock was obtained 9 1 2 Calling the el_start_locked Routine The following code shows how the el_ start routine calls the el_start_locked routine which starts the transmit operation el_start_locked sc ifp 4 Calls theel_ start locked routine which performs the tasks that are related to the start operation 9 1 3 Releasing the Simple Lock and Resetting the IPL 9 2 The following code shows how the el_start routine releases the simple lock and resets the IPL simple unlock amp sc gt el_softc_lock 1 sp
44. memory that the adapter uses and returns ESUCCESS to indicate that the unattach operation completed successfully Implementing the unattach Routine 7 5 8 Implementing the Initialization Section The initialization section prepares the network interface to transmit and receive data packets It can also allocate mbuf data structures for the receive ring The if _e1 device driver implements the following routines in its initialization section e el init Section 8 1 e el init locked Section 8 2 8 1 Implementing the el_init Routine Theel_init routineis a jacket routinethat performs the following tasks e Determines whether the PCMCIA card is in the slot Section 8 1 2 e Sets the IPL and obtains the simple lock Section 8 1 3 e Calls theel init locked routine to perform the initialization Section 8 1 4 e Releases the simple lock and resets the IPL Section 8 1 5 e Returns the status from el init locked Section 8 1 6 8 1 1 Setting Up the el_init Routine The following code shows how to set up theel_init routine static int el_init int unit 1 register struct l softe sc el_softc unit 2 register struct ifnet ifp amp sc gt is_if 3 int i s 4 1 Specifies the unit number of the network interface as the only argument toel_init 2 Declares a pointer tothe el_softc data structure called sc and initializes it to the el_softc data
45. oie ee 12 8 Adding the Device toa Multicast Group SIOCADDMULTI Oct Command sos naea Wels ootetiiaecaddan sata lelandadllen esels 12 9 Deleting the Device froma Multicast Group SIOCDELMULTI Lodi Command i aenaran Levee tae ete ae aaa Coke aed 12 10 Accessing Network Counters SIOCRDCTRS and SIOCRDZCTRS ioctl Commands cccc cece cece cece eens 12 11 Bringing Up the Device SIOCSIFADDR ioctl Command 12 12 Using Currently Set Flags SIOCSIFFLAGS ioctl Command 12 13 SettingtheIP MTU SIOCSIPMTU ioctl Command 12 14 Setting the Media Speed SIOCSMACSPEED ioctl COMMANG a a a a oo ee o N 10 2 10 2 11 1 11 2 12 2 12 3 12 3 12 4 12 4 Contents vii 12 15 Resetting the Device SIOCIFRESET ioctl Command 12 16 Setting Device Characteristics SIOCIFSETCHAR ioctl Command siaa e e rence tye a water anes OT eE AEE 12 17 Releasing the Simple Lock and Resetting the IPL 13 Implementing the Interrupt Section 13 1 Implementing the el_intr Routine cece eee eee eee eee 13 1 1 Setting the IPL and Obtaining the Simple Lock 13 1 2 Rearming the Next Timeout cceeeeeee eect eee eee 13 1 3 Reading the Interrupt Status ce cece eee eee eee 13 1 4 Processing Completed Receive and Transmit Operations 13 1 5 Acknowledging the Interrupt cceeeeeeeee eee eee 13 1 6 Transmitting Pending Frames cc
46. oxb 3 enum w1_txstat 4 TX_CM 0x80 TX_IS 0x40 TX_JB 0x20 TX_UN 0x10 TX_MC 0x08 TX_OF 0x04 TX_RE 0x02 Defining Device Register Offsets 2 9 i define TX_INT oxs000 5 define W1_RXDATA oxo 6 define W1_TXDATA oxo 7 define W1_FREETX oxc 8 1 2 Defines the offset for the receive status register Defines an enumerated data type called w1_rxstat Theif_el device driver can assign one of the following values toW1_RXSTAT the receive status register RX_IC Indicates an incomplete operation RX_ER Indicates an error in the operation RX_EM If any of the bits are set in the mask indicates that an error has occurred RX_EOR Indicates an overrun error in the operation RX_ERT Indicates a run time error RX_EAL Indicates an alignment error RX_ECR Indicates a CRC error RX_EOS Indicates an oversize error RX_BYTES Mask used to determine the number of bytes received Defines the offset for the transmit status register Defines an enumerated data type called w1_txstat Theif_el device driver can assign one of the following values to W1_TXSTAT the transmit status register TX_CM Indicates that the transmission completed TX_IS Indicates that the device should interrupt when a transmission is successfully completed TX_JB Indicates a jabber error TX_UN Indicates an underrun This is a serio
47. performance of the interface and network The ifnet data structure also contains a queue of data packets that the network driver sends to the network device These packets are linked lists of mbuf data structures Each such linked list represents one data packet Depending on how a network driver fills in certain members of the ifnet data structure the upper level network code fragments the data to be sent out over a network In the case of the Ethernet network interface the upper level code never hands off to the driver a single packet that exceeds 1514 bytes 1 1 Include Files Section for a Network Driver A network device driver includes header files that define data structures and constant values that the driver references A network device driver includes some of the same files as a block or character device driver such as errno h It can also include the header files that are specific to network device drivers For example include lt net net_globals h gt include lt sys socket h gt include lt net if h gt include lt net if_types h gt The following code shows the include files section for the if e1 device driver include lt sys param h gt include lt sys systm h gt include lt sys mbuf h gt include lt sys buf h gt include lt sys protosw h gt include lt sys socket h gt include lt sys vmmac h gt include lt vm vm_kern h gt include lt sys ioctl h gt 1 include lt sys errno h gt include lt sys time h g
48. routine 10 1 errno h header file 1 3 etc sysconfigtab database 14 1 event counting 13 10 external declarations if_el device driver 1 5 F FIFO maintenance information 3 7 flag processing special 8 8 setting debug 8 9 using currently set 12 10 forward declarations if_el device driver 1 5 frames transmitting pending 13 4 H hardware address determining a change 5 12 reading current 12 5 header file devdriver h 1 4 errno h 1 3 if_elreg h 2 1 ioctl h 1 4 sysconfig h 1 4 header length setting up 6 2 if_elreg h file w3_eepromdata structure definition 2 13 if_elreg h header file device register header file 2 1 include files section 1 3 init interface 8 1 initialization section 1 10 implementing 8 1 interface attach 6 1 configure 4 1 init 8 1 ioctl 12 1 network driver 6 6 unattach 7 1 watchdog 10 1 interrupt acknowledging 13 4 dearing 8 5 enabling 8 10 indicating service 13 5 information in el_softc data structure 3 9 register offset definitions 2 1 status 13 3 Index 3 interrupt handler enabling 6 10 ID 3 6 registering 5 15 interrupt section 1 11 implementing 13 1 ioctl command SIOCADDMULTI 12 6 SIOCDELMULTI 12 7 SIOCDISABLBACK 12 4 SIOCENABLBACK 12 4 SIOCIFRESET 12 11 SIOCIFSETCHAR 12 11 SIOCRDCTRS 12 8 SIOCRDZCTRS 12 8 SIOCRPHYSADDR 12 5 SIOCSIFADDR 12 9 SIOCSIFFLAGS 12 10 SIOCSIPMTU 12 10 SIOCSMACSPEED 12 11 SIOCSPHYSADDR 12
49. sc gt hid 1 1 Callsthe handler enable routine to enable a previously registered interrupt handler The el_probe routine calls handler add to register the interrupt handler and it stores the handler ID in the hid member of the el_softc data structure for this device 6 12 Starting the Polling Process The following code shows how the el_attach routine starts the polling process if el_polling amp amp sc gt polling flag 1 sc gt polling flag 1 timeout void el_intr void unit 1 hz el_pollint else sc gt polling flag 0 2 return 0 Starts the polling process if the el_ polling attribute specifies that polling is to be done To start the polling process el attach setsthepolling flag member to 1 true then calls the timeout routine to schedule the interrupt handler to run at some point in the future timeout is called with the following arguments e A pointer totheel intr routine whichis theif e1 device driver s interrupt handler e Theunit variable which contains the controller number associated with this device This argument is passed totheel_intr routine e Theel_pollint variable which specifies the amount of time to delay before calling the el _intr routine 2 If the user requests that polling be disabled el attach sets the polling flag member to 0 false 6 10 Implementing
50. sets the media setting in the hardware el_reset ifp gt if_unit I break 2 else 1 Directs the hardware to use the media setting that was selected in the previous section 2 Breaks out of the packet transmit loop because the media setting has been determined 5 3 10 Building the Test Packet The following code shows how theel_autosense thread routine builds a test packet to transmit beopy el_junk_msg mtod m caddr_t EL JUNK SIZE 1 beopy sc gt is_addr mtod m caddr_t 6 2 beopy sc gt is_ addr mtod m caddr_t 6 6 3 m gt m_pkthdr len m gt m_len EL _JUNK_ SIZE Loads the junk message into the mbuf data structure N Sets the destination address as the address of the adapter ao Sets the source address as the address of the adapter 5 3 11 Transmitting the Test Packet The following code shows how the el_autosense thread routine transmits the test packet s splimp simple lock amp sc gt el_softc_lock IF_ENQUEUE amp ifp gt if_snd m el_start_locked sc ifp simple unlock amp sc gt el_softc_lock splx s 5 22 Implementing the Autoconfiguration Support Section probe 5 3 12 Setting a Timer for the Current Kernel Thread The following code shows how the el_autosense thread routine sets a timer for the current kernel thread wait
51. statistics in the if el driver s el_softc data structure consists of information about timeout and interrupt events 3 8 Defining the softc Data Structure The following code shows the declarations of the timeout and interrupt information in the if _e1 devicedriver s el_softc data structure unsigned long txreset 1 unsigned long xmit_tmo 2 unsigned long tint 3 unsigned long rint 4 1 Contains the number of transmitter error resets 2 Contains the number of times that transmit timeouts occurred The el_watch routine increments this member 3 Contains the count of transmit interrupts 4 Contains the count of receive interrupts 3 13 Defining Autosense Kernel Thread Context Information The autosense kernel thread context information in the if e1 driver s el_softc data structure consists of information about the kernel thread that performs the autosense operation For the if _e1 driver this kernel thread is called el _autosense thread The following code shows the declarations of the autosense kernel thread variables in the if _e1 device driver s el_softc data structure Theif el device driver uses kernel threads to perform the tasks that are related to autosensing the media However you can choose other methods instead of kernel threads thread_t autosense thread 1 int autosense flag 2 Contains the autosense
52. structure for this 3Com 3C5x9 device 2 Sets the intr member of the el intr info data structure to el_intr whichis theif el devicedriver s interrupt handler 3 Sets the param member of the el_intr_info data structure tothe controller number for the controller data structure for this 3Com 3C5x9 device 4 Sets the config type member of theel intr info data structure to the constant CONTROLLER_CONFIG_TYPE which identifies the if el driver type as a controller driver 5 If the if el driver operates on the PCMCIA bus indicates that the if_el driver can handle shared interrupts 6 Sets the ih_bus member of the el _ihandle data structure tothe bus data structure for the if _e1 device driver The bus data structure is referenced through the bus_hd member of the controller data structure for this 3Com 3C5x9 device 7 Setstheih_bus_ info member of theel_ihandle data structure tothe address of the bus specific information data structure el_intr_info 8 Calls the handler add routine to register the device driver s interrupt handler and its associated ihandler_t data structure with the bus specific interrupt dispatching algorithm Implementing the Autoconfiguration Support Section probe 5 15 This routine returns an opaque ihandler id _t key which is a unique number that identifies the interrupt handler to be acted on by subsequent calls tohandler del handler
53. the Autoconfiguration Support Section attach 7 Implementing the unattach Routine Theel_unattach routineis called to stop the device and to free memory and other resources prior to unloading the driver or powering off the bus to which the device is attached The el_unattach routine undoes everything that was performed by the el _probe andel_ attach routines Note The PCMCIA bus does not support the el_unattach routine Theel_unattach routine performs the following tasks e Verifies that the interface has shut down Section 7 2 e Obtains and releases the simple lock Section 7 3 e Disables the interrupt handler Section 7 4 e Terminates the autosense thread Section 7 5 e Unregisters the PCMCIA event callback routine Section 7 6 e Stops the polling process Section 7 7 e Unregisters the shutdown interface Section 7 8 e Terminates the simple lock Section 7 9 e Unregisters the card from the hardware management database Section 7 10 e Frees data structures and resources used by the adapter Section 7 11 7 1 Setting Up the el_unattach Routine The following code shows how to set up the el_unattach routine static int el _unattach struct bus bus 1 struct controller ctlr int unit ctlr gt ctlr num 2 int s status Implementing the unattach Routine 7 1 struct el softe sc el_softc unit struct ifnet ifp amp sc gt is_if
54. the IPL and obtains the simple lock Section 9 1 1 e Callstheel start locked routine Section 9 1 2 e Releases the simple lock and resets the IPL Section 9 1 3 9 1 1 Setting the IPL and Obtaining the Simple Lock The following code shows how the el_start routine sets theIPL and acquires the simple lock static void el_start struct ifnet ifp register int unit ifp gt if_unit s register struct el _softc sc el _softc unit s splimp L121 if simple_lock try amp sc gt el_softc_lock 2 splx s 3 return Calls the splimp routine to mask all LAN hardware interrupts On successful completion splimp stores an integer value in thes variable This integer value represents the CPU priority level that existed before the call tosplimp Implementing the Start Section 9 1 Calls the simple lock try routine to try to assert a lock with read and write access for the resource that is associated with the specified simple lock Theel_start routine calls simple lock try rather than simple lock because simple lock try returns immediately if the resource is already locked simple lock spins until the lock has been obtained Make sure that you call simple lock _try when you need a simple lock but the code cannot spin until the lock is obtained In this example simple lock _try was used as an optimization If the simple
55. the Interrupt Section The interrupt section of a network device driver contains the code that is called whenever the network interface transmits or receives a frame The if_el device driver implements the following routines in its interrupt section el _intr Section 13 1 el _rint Section 13 2 el_tint Section 13 3 el_error Section 13 4 Note The if_el device driver implements a shared interrupt handler A shared interrupt handler is a driver routine that is registered to take advantage of the shared interrupt framework that Tru64 UNIX provides for hardware devices that share an interrupt line The ISA bus does not currently support shared interrupts 13 1 Implementing the el_intr Routine The if_el device driver implements an interrupt handler called el _intr which performs the following tasks Sets the interrupt and priority level IPL and obtains the simple lock Section 13 1 1 Rearms the next timeout Section 13 1 2 Reads the interrupt status Section 13 1 3 Processes completed receive and transmit operations Section 13 1 4 Acknowledges the interrupt Section 13 1 5 Transmits pending frames Section 13 1 6 Releases the simple lock and resets the IPL Section 13 1 7 Indicates that the interrupt was serviced Section 13 1 8 Implementing the Interrupt Section 13 1 13 1 1 Setting the IPL and Obtaining the Simple Lock The following code shows how the el_intr routine sets the CPU s IPL
56. the receive RX reset command CMD_RXRESET 8 2 2 Clearing Interrupts The following code shows how the el_init locked routine clears interrupts 8 4 Implementing the Initialization Section This task is specific to the 3Com 3C5x9 device Make sure that you perform similar initialization tasks for the hardware device that your network driver controls WRITE _CMD sc CMD _ACKINT 0xff 1 1 Calls the WRITE CMD macro to write data to the command port register The data written to the command port register is the acknowledge interrupt command CMD_ACKINT plus a mask that specifies that all interrupts are to be acknowledged 8 2 3 Starting the Device The following code shows how the el_init locked routine starts the device This task is specific to the 3Com 3C5x9 device Make sure that you perform similar initialization tasks for the hardware device that your network driver controls WRITE _CMD sc CMD _WINDOWO i READ CCR sc WRITE _CCR sc CCR_ENA i 4 WRITE _RCR sc sc gt irg lt lt 12 RCR_RSV L2 Calls the WRITE_CCR macro to write data to the 3Com 3C5x9 device s configuration control register The data to be written consists of the original register contents but with the enable adapter bit CCR_ENA set 2 Calls the WRITE _RCR macro to write data to the 3Com 3C5x9 device s resource configuration register The data to be written is th
57. unsigned char ifr gt ifr_addr sa_data switch i case LAN MULTI_CHANGED if sc gt is_multi lan_nmulti 0 need_reset j break case LAN MULTI NOT CHANGED break case LAN MULTI FAILED default status EINVAL break if ifp gt if_flags amp IFF_RUNNING amp amp need_reset el _reset_locked sc ifp unit Implementing the ioctl Section 12 7 if sc gt debug j 0 printf el d Dump of multicast table after DEL d entries n unit sc gt is_multi lan_nmulti for i 0 i lt sc gt is_ multi lan_nmulti i unsigned char maddr LAN_GET_ MULTI amp sc gt is multi maddr j printf sd s muse d n i 1 ether sprintf maddr sc gt is_multi lan_mtable j 1 muse lan_build_mclist mclist_buf NET_SZ MCLIST amp sc gt is_ multi 3 lan_set_attribute sc gt ehm current_val NET _MCLIST_NDX mclist_buf break 1 Determines whether the cmd argument is SIOCDELMULTI 2 Examines the type of the multicast address and decrements the appropriate counter The el_ioct1 routine removes the capability from the device only when there are no more active multicast addresses 3 Builds a text string that lists all currently active multicast addresses and sets this list as an enhanced hardware management EHM attribute for this network device 12 10 Accessing Network Counters SIOCRDCTRS and 12 8 SIOCRDZCTRS io
58. 00000 3 10 4 Implementing the Configure Section 4 1 Declaring Configure Related Variables and the cfg_subsys_attr_t Data Structure cece eee eee eee eee 4 1 4 2 Setting Up the el_configure Routine ssessssessessesresesrssr 4 3 5 Implementing the Autoconfiguration Support Section probe 5 1 Implementing the el_ probe Routine cceeeeeeee eee eee 5 1 5 1 1 Setting Up the el_probe Routine ccc cece eee ees 5 2 5 1 2 Checking the Maximum Number of Devices That the Driver SUPPOFES iieri ees a nee Geaa eee the 5 4 5 1 3 Performing Bus Specific Tasks ceeeeeeee eee eee eee 5 4 5 1 4 Allocating Memory for the softc Data Structure 5 6 5 1 5 Allocating the ether_driver Data Structure ccecce 5 7 5 1 6 Initializing the Enhanced Hardware Management Data Structuur ES sacte santa Relies aa teva tina taken EA Taa 5 8 5 1 7 Computing the CSR Addresses 0c cece cece eee eee 5 8 5 1 8 Setting Bus Specific Data Structure Members 5 8 5 1 9 Handling First Time Probe Operations 00085 5 10 5 1 10 Handling Subsequent Probe Operations 065 5 12 5 1 11 Registering the Interrupt Handler ceceeee eee 5 14 5 1 12 Saving the controller and softc Data Structure Pointers 5 16 5 1 13 Trying to Allocate Another controller Data Structure 5 16 5 1 14 Registering the shutdown Routine c cece eee eee 5 17 5 2 Implementi
59. 24 64 static void el_tint struct el_softc sc struct ifnet ifp int count TXLOOP volatile unsigned int status sc gt tint 1 Increments a counter of the number of the transmit interrupts that have been processed 13 3 2 Reading the Transmit Status and Counting All Significant 13 10 Events The following code shows how the el_tint routine reads the transmit status and counts all significant events status READ_TXS sc 1 while status amp TX_CM lt lt 8 amp amp count gt 0 if status amp TX_JB TX_UN lt lt 8 2 ifp gt if_oerrors sc gt ctrblk est_sendfail sc gt txreset WRITE TXS sc status 3 Implementing the Interrupt Section WRITE _CMD sc CMD _TXRESET DELAY 10 4 WRITE _CMD sc CMD_TXENA 1 Calls the READ Txs macro to read the transmit status from the transmit status register 2 Examines the status for a jabber or an underrun error If either of these errors happened then the transmitter must be reset 3 Clears the transmit status register and resets the transmitter 4 Calls the DELAY macro to wait for 10 microseconds before reenabling the transmitter 13 3 3 Managing Excessive Data Collisions The following code shows how the el_tint routine manages excessive data collisions else if status amp TX_MC lt lt 8
60. 5 ioctl interface 12 1 ioctl section 1 11 implementing 12 1 iocti h header file 1 4 IP MTU setting 12 10 IPL resetting in el_init 8 3 in el_intr 13 4 in e_ioctl 12 13 in el_start 9 2 in el_watch 10 2 setting in el_init 8 2 in el_intr 13 2 in el_ioctl 12 3 in el_start 9 1 in el_watch 10 1 ISA bus initializing bus specific data structure 5 8 probing 5 4 Index 4 K kernel thread blocking 5 19 setting a timer for 5 23 starting 5 10 L LAN setting address 8 8 settingmedia 8 6 loopback mode disabling 12 4 enabling 12 4 MAC address enabling 12 5 macros driver specific 1 8 media establishing new 5 25 marking the setting in the hardware 5 22 setting up 6 3 setting up new 5 24 media address setting up 6 2 media speed setting 12 11 media state information 3 4 memory allocation el_softc data structure 5 6 memory mapping 8 7 multicast adding an address 12 6 defining table information 3 6 deleting an address 12 7 N network device driver 1 1 autoconfiguration support section 1 10 configure section 1 10 declarations 1 4 environment 1 1 include files 1 3 initialization section 1 10 interrupt section 1 11 ioctl section 1 11 output section 1 11 register offsets 2 1 reset section 1 11 start section 1 10 watchdog section 1 11 network layer attaching 6 8 O operational window setting 8 10 outgoing bytes accounting fo
61. Declares as an argument a pointer toa bus data structure and a controller data structure for this controller The controller data structure contains such information as the controller type the controller name and the current status of the controller This completely identifies the adapter that is being unattached Declares a unit variable and initializes it to the controller number for this controller This controller number identifies the specific 3Com 3C5x9 controller that is being unattached The controller number is contained in the ct1r_num member of the controller data structure for this device 7 2 Verifying That the Interface Has Shut Down The following code verifies that the interface is down Make sure that other errors returned by if detach do not stop interface shutdown 4 status if detach ifp 1 if status EBUSY 2 return status else if status ESUCCESS 3 detachpfilter sc gt is_ ed ifp gt if_flags amp IFF_RUNNING 4 Calls if detach to remove this interface from the list of active interfaces If the interface is still in use it cannot be detached so failure is returned If the interface is not in use detaches it from the list of those that the packet filter monitors Marks the interface as no longer running 7 3 Obtaining the Simple Lock and Shutting Down the Device The following code shows how the el_unat
62. EDR sc WRITE _CMD sc define define define define define define define define define define define define define define define define EAD STS sc R W READ_DATA sc READ_ND sc WRITE _ND sc READ_MD sc WRITE MD sc READ_TXF sc READ_RXF sc WRITE_AD1 sc WRITE_AD2 sc WRITE_AD3 sc READ_TXS sc WRITE_TXS sc READ_RXS sc READ_FDP sc val val val val val RITE DATA sc val val val val val val val READ BUS _D RITE BUS EAD BUS _D RITE BUS RITE BUS RITE BUS EAD BUS _D RITE BUS SBASBzzV7 2 EAD BUS _D RITE BUS D BUS _D D BUS D RITE BUS EAD BUS _D RITE BUS D BUS _D D BUS D RITE BUS RITE BUS RITE BUS EAD BUS _D RITE BUS READ BUS _D READ BUS _D 3 0 o 5 6 0 0 Soa o oo D D D D D D 3 D D D D D D 1 T ak T 1 3 2 6 6 6 6 6 6 6 6 6 6 6 6 6 2 6 6 6 6 6 6 6 6 6 mb c sc gt reg4 c sc gt reg6 sc gt reg8 sc gt regA c sc gt regE s s s s sc gt data sc sc sc gt reg6 sc sc gt regA sc sc sc gt reg0 sc gt reg2 sc gt reg4 sc gt regA sc gt regA sc gt reg8 sc gt reg4 gt reg4 gt reg6
63. Only network device drivers that operate on multiple CPUs need to obtain a simple lock The simple lock mechanism protects resources in a symmetric multiprocessing environment The obta s si following code shows how the el_init routine sets the IPL and ins the simple lock splimp a mple_lock amp sc gt el_softc_lock 2 Calls the splimp routine to mask all LAN hardware interrupts Upon successful completion splimp stores an integer value in the s variable This value represents the CPU priority level that existed before the call to splimp Calls the simple _lock routine to assert a lock with exclusive access for the resource that is associated with the el_softc_lock data structure This means that no other kernel thread can gain access to the locked resource until you call simple_unlock to release it Because simple locks are spin locks simple _lock does not return until the lock has been obtained 8 2 Implementing the Initialization Section Theel_softc_lock member of the el_softc data structure points to a simple lock data structure The if _e1 device driver declares this data structure by calling the decl_simple_ lock data routine 8 1 4 Calling the el_init_locked Routine The following code shows how the el_init routine calls the el_init_locked routine which performs the actual initialization tasks i el_init_locked sc ifp unit
64. R_BASE 0x001f i define WO_RCR 0x8 7 enum w0_rcr L8 RCR_IRQ 0xf000 RCR_RSV 0x0f00 i define WO_ECR oxa 9 enum w0_ecr 10 ECR_EBY 0x8000 ECR_TST 0x4000 ECR_CMD 0x00ff ECR_READ 0x0080 Defining Device Register Offsets 2 5 ECR_WRITE 0x0040 ECR_ERASE 0x00c0 ECR_EWENA 0x0030 ECR_EWDIS 0x0000 ECR_EAR 0x0020 ECR WAR 0x0010 Yg define W0_EDR oxc 11 Defines the offset for the manufacturer ID register Defines the offset for the adapter ID register Defines the offset for the configuration control register A N Defines an enumerated data type called wo_ccr The if_el device driver can assign one of the following values to wo_CCR the configuration control register CCR_PCMCIA If set thisisa PCMCIA bus Otherwise it is an ISA bus CCR_AUI If set the attachment unit interface AUI is available CCR_10B2 If set the 10Base2 receiver is available CCR_ENDEC If set the internal encode decode ENDEC loopback is used CCR_RESET Reset adapter CCR_ENA Enable adapter 5 Defines the offset for the address control register 6 Defines an enumerated data type called wo_acr Theif_ el device driver can assign one of the following values to Wo_AcR the address control register ACR_10BT If set the information transmission rate is at 10 Mb sec for
65. The 12 10 Implementing the ioctl Section SIOCSMACSPEED and SIOCIFSETCHAR ioct1 commands perform some of the same tasks case SIOCSMACSPEED 1 beopy ifr gt ifr_data u_char amp speed sizeof u_short if speed 0 amp amp speed 10 2 status EINVAL break break 1 Determines whether the cmd argument is SIOCSMACSPEED 2 Ifthe LAN speed passed is anything other than 10 0 means no change fails the request The if e1 device can only operate at 10 Mb per second 12 15 Resetting the Device SIOCIFRESET ioctl Command The following code shows how the e1_ioct1 routine implements the SIOCIFRESET ioct1 command toreset the device Support for the SIOCIFRESET command is optional You can choose whether or not your driver supports it case SIOCIFRESET 1 el_reset_locked sc ifp unit 2 break 1 Determines whether the cmd argument is SIOCIFRESET 2 Callstheel_ reset _locked routinetorestart the network interface 12 16 Setting Device Characteristics SIOCIFSETCHAR ioctl Command The following code shows how the el_ioct1 routine implements the SIOCIFSETCHAR ioctl command to set characteristics case SIOCIFSETCHAR 1 need_reset 0 2 if ifc gt ifc_media_speed 1 amp amp ifc gt ifc_media_speed 10 3 status EINVAL break
66. Tru64 UNIX Writing Network Device Drivers Part Number AA RNG2A TE December 2000 Product Version Device Driver Kit Version 2 0 Operating System and Version Tru64 UNIX Version 5 0A or higher This manual contains information that systems engineers need to write network device drivers that operate on any bus Compaq Computer Corporation Houston Texas 2000 Compaq Computer Corporation Compaq and the Compaq logo Registered in U S Patent and Trademark Office Tru64 is a trademark of Compaq Information Technologies Group L P in the United States and other countries UNIX and X Open are trademarks of The Open Group in the United States and other countries All other product names mentioned herein may be trademarks of their respective companies Confidential computer software Valid license from Compaq required for possession use or copying Consistent with FAR 12 211 and 12 212 Commercial Computer Software Computer Software Documentation and Technical Data for Commercial Items are licensed to the U S Government under vendor s standard commercial license Compaq shall not be liable for technical or editorial errors or omissions contained herein The information in this document is provided as is without warranty of any kind and is subject to change without notice The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products Nothing herein should be construed as c
67. Z MCLIST 12 Specifies a pointer tothe ifnet data structure for an if _e1 device Specifies the ioct 1 command Specifies a pointer to ioct 1 command specific data to be passed to or initialized by the device driver Declares a pointer tothe el_softc data structure that is called sc and initializes it tothe el_softc data structure for this device Declares a unit variable and initializes it to the unit number for the device Casts the data argument toa data structure of type if req for use with the SIOCPHYSADDR SIOCADDMULTI SIOCDELMULTI SIOCSTPMTU and SIOCSMACSPEED ioctl commands Implementing the ioctl Section Casts the data argument to a data structure of type ifdevea for use with the SITOCRPHYSADDR ioct1 command Casts the data argument toa data structure of type ctrreq for use with the STOCRDCTRS and SIOCRDZCTRS ioct1 commands Casts the data argument toa data structure of type ifchar for use with the SIOCIFSETCHAR ioctl command Declares a lock_on variable and sets it to the value 1 true which indicates that the simple lock is held Theel_ioct1 routinesets this variable to the value 0 false when the simple lock is no longer in effect Declares a status variable and sets it to the constant ESUCCESS Declares an ifmtu variable that stores the requested MTU value for the SIOCIPMTU Command Declares a speed variable that stores the r
68. _len while ms NULL io_blockwrite vm_offset_t dat 2 sc gt data u_long len amp 3 HANDLE LONGWORD dat len amp 3 ms ms gt m_next i len 4 3 if ms NULL if i val 0 for j 0 j lt i j val dat lt lt 8 j WRITE DATA sc val for j 0 j lt i j val dat lt lt 8 j dat mtod ms unsigned char if ms gt m_len lt 4 i for j 0 j lt ms gt m_len j val dat lt lt 8 j i ms NULL else len ms gt m_len 4 i for j i j lt 4 j val dat lt lt 8 j WRITE DATA sc val else dat mtod ms unsigned char len ms gt m_len Requests an interrupt upon completion of the transmit operation 9 6 Implementing the Start Section 2 Copies transmit data from memory to the card using 32 bit writes Only a multiple of 4 bytes can be copied this way 3 If some number of bytes fewer than 4 remain in the current memory buffer the driver either copies those bytes directly to the card if they were the last bytes for the entire frame or combines those bytes with bytes from the next memory buffer if there is more data for this frame 9 2 4 Accounting for Outgoing Bytes The following code shows how the el_start_locked routine accounts for the outgoing bytes sc gt txfree sc gt txfree m gt m_pk
69. a is shielded twisted pair cable LAN MEDIA FIBER The mode for the media is any fiber based media LAN MEDIA _AUI The mode for the media is the attachment unit interface AUI LAN MEDIA 4PAIR The mode for the media is four pair cable iAN_MODE_AUTOSENSE The hardware determines the media Defines an alternate name for referencing the lan media state member of the lan_media data structure The lan media state member will be set only if lan media_mode has the value LAN MODE _AUTOSENSE This member is typically set in the driver s probe routine The lan_media_state member can be set to one of the following constants which are defined in the lan_common h file LAN _MEDIA_STATE_SENSING Themediais currently in the autosensing state LAN MEDIA STATE DETERMINED The media state has been determined Defines an alternate name for referencing the 1an_media member of the lan_media data structure The lan_media member specifies the currently set media The value that is stored in the lan_media member is valid in the autosense mode only if the lan_media_state member is set tothe constant LAN MEDIA STATE DETERMINED The value that is stored in lan_media reflects the current setting of the device In contrast the value that is stored in the lan_media_mode member usually reflects how the media is to be selected Typically you set the lan media Defining the softc Data Structure 3 5 member in the
70. ady been probed the el_probe routine performs the following tasks e Reads the EEPROM and saves it toa temporary data structure e Reads and saves the device s physical address e Starts the autosense thread to determine the media type The following code shows how the el_probe routine performs these tasks if sc gt reprobe 1 if multi_func_flag 2 bzero caddr_t amp tuple data sizeof struct tuple data_info tuple data_infop amp tuple data tuple infop struct tuple_info amp tuple_data tuple _infop gt socket short card_infop gt socket_vnum tuple infop gt attributes 0 tuple _infop gt DesiredTuple 0x88 status GetFirstTuple tuple_infop if status SUCCESS tuple data_infop gt TupleOffset 0 tuple data_infop gt TupleDataMax u_short TUPLE DATA MAX status GetTupleData tuple_data_infop if status SUCCESS ee unsigned char amp sc gt eeprom for i 0 i lt sizeof struct w3_eeprom i ee tuple _data_infop gt TupleData i ee else printf el d Can t read multifunction card s eeprom n unit if sc gt ispcmcia pemcia_unregister_event_callback card_infop gt socket_vnum CARD_REMOVAL_ EVENT caddr_t el_card_remove if_dealloc sc gt is_ed lan_ehm_free amp sc gt ehm FREE sc M DEVBUF return 0 else printf el d Can t read multifunction card s eeprom n unit if sc gt
71. an configure Routines with the prefix lan_ residein the lan_common c source file A network driver s configure routine can simply call lan_configure to carry out the following tasks e CFG OP CONFIGURE e CFG OP RECONFIGURE e CFG OP _UNCONFIGURE e CFG OP QUERY Theif_el driver s configure section contains an attributes data structure and the el_configure routine The following sections describe how to initialize the cfg _subsys attr t data structure and how toset up the el_configure routine e Dedaring configure related variables and initializing the cfg_subsys attr_t data structure Section 4 1 e Settingup theel configure routine Section 4 2 4 1 Declaring Configure Related Variables and the cfg_subsys_attr_t Data Structure As part of implementing a device driver s configure interface you declarea number of variables and initializethe cfg _subsys attr_t data structure Implementing the Configure Section 4 1 The following code shows the declaration of the variables and the initialization of the cfg_subsys attr_t data structure for theif el device driver static unsigned char el pcmcia_optiondata 400 4 static unsigned char el_isa_optiondata 300 2 static unsigned char el _unused 300 static int el polling 0 3 static int el _pollint 16 4 static int el configured 0 5 static struct lan_config data el data 6 LAN CONFIG VERSION ID 0 amp eldriver amp e
72. and ECR_EWENA Represents an EEPROM enable erase or write command ECR_EWDIS Represents an EEPROM disable erase or write command ECR_EAR Represents an EEPROM erase all registers command ECR_WAR Represents an EEPROM write all registers command 11 Defines the offset for the EEPROM data register 2 4 Window 3 Configuration Register Offset Definitions The window 3 configuration registers consist of the additional setup information registers shown in Figure 2 2 Defining Device Register Offsets 2 7 Figure 2 2 Window 3 Configuration Registers Constant W3_ASI2 W3_ASIO ZK 1268U Al The following code shows the offset definitions for the registers that are associated with the window 3 configuration registers define W3_ASI2 0x2 define W3_ASIO 0x0 enum w3_asi 3 AS_ISA 0x00040000 AS_PNP 0x00080000 AS_BOT 0x000c0000 AS_NON 0x00000000 PAR _35 0x00000000 PAR_13 0x00010000 PAR_11 0x00020000 RS 0x00000030 RW 0x00000008 RSIZE8 0x00000001 ASI N o RSIZE32 0x00000002 1 2 Defines the offset for the additional setup information register 2 Defines the offset for the additional setup information register 0 Defines an enumerated data type called w3_ asi Theif el device driver can assign one of the following values to w3_ASI2 and w3_ASTO the additional setup information registers ASI TAS ISA ASI IAS PNP
73. ap If an mbuf was successfully allocated copies the packet data into the mbuf receive data are 32 bit aligned Computes the length of the received data excluding the size of the MAC header Records this length in the mbuf header Sets the receiving interface to be the if _e1 device by saving theif el device s ifnet data structure address in the mbuf header Aligns the data pointer so that the IP header will be aligned on a 32 bit boundary Make sure that your network driver does this also Obtains the pointer to the data and calculates the number of longwords in the FIFO transfer Because the EtherLink III performs no multicast filtering if the promiscuous bit and all multicast bits are not set determines whether any multicast addresses are actually wanted Reads the first two longwords to determine whether the packet is sent to a multicast address Determines whether the packet contains either a multicast or a broadcast group address Because the driver receives all broadcasts makes sure that the group address is not the broadcast address Calls the LAN FIND MULTI macro to find the multicast address If the multicast is not found scraps the packet 13 2 4 Copying the Received Packet into the mbuf The following code shows how the el_rint routine copies the received packet into the mbuf io_blockread sc gt data vm_offset_t dat u_long len HANDLE LONGWORD 1 13 8 Implementing the Inter
74. appropriate message on the console terminal then returns the value 0 zero to indicate that the probe operation failed See the if el source file in the examples directory that is installed with the device driver kit for a listing of the el isa _activate routine 15 If the driver is not operating on either the PCMCIA or ISA bus calls the printf routine to display an appropriate message on the console terminal then returns the value 0 zero to indicate that the probe operation failed 5 1 4 Allocating Memory for the softc Data Structure 5 6 The following code shows how the el_probe routine allocates memory for the if_e1 device driver s softc data structure If the device has already been probed the driver does not need to allocate the data structure This can happen if the user removed and then reinserted the device an operation that is only possible for PCMCIA versions of the adapter Implementing the Autoconfiguration Support Section probe if el_softc unit 4 sc el _softc unit sc gt cardout sc gt reprobe else 2 0 1 MALLOC sc void sizeof struct el_softc M_DEVBUF M WAIT M_ ZERO if sc 13 printf el d el_probe failed to get buffer memory for softc n unit return 0 4 1 If the user removed and returned the PCMCIA card to its slot e Locates the existing el_softc data structure f
75. ate and read from hardware registers These routines are specific to the if_e1 device driver To learn how the driver handles these tasks see the source listing in the examples directory that is installed with the device driver kit The following sections describe how to use the probe interface e Implementing the el probe routine Section 5 1 e Implementing the el shutdown routine Section 5 2 e Implementing theel autosense thread routine Section 5 3 5 1 Implementing the el_probe Routine Theel_ probe routine performs the following tasks e Checks the maximum number of devices that the driver supports Section 5 1 2 e Performs bus specific tasks Section 5 1 3 e Allocates memory for the softc and ether driver data structures Section 5 1 4 and Section 5 1 5 e Initializes the enhanced hardware management data structure Section 5 1 6 e Computes the control and status register addresses Section 5 1 7 e Sets bus specific data structure members Section 5 1 8 e If this is the first time the device has been probed copies data from the EEPROM reads and saves the device s physical address and starts the autosense kernel thread to determine the media type Section 5 1 9 Implementing the Autoconfiguration Support Section probe 5 1 For subsequent probe operations reads the EEPROM to determine if the hardware address and thus the adapter has changed Section 5 1 10 Registers the interrupt handler Sec
76. c _card_remove int struct el softe j static int isa reset all io handle t int struct controller static int _isa_activate io_handle t int struct controller static unsigned short el _isa_read_offset io_ handle t int static void el _wait struct el _softc static void el_autosense thread struct el_softc j static int el_card_out struct el _softc j extern struct timeval time 3 extern task t first task 4 voo7o7 070 00 DO DDAADAMA MDA MO O 1 Declares the function prototype definitions for all exported functions 2 Declares the driver interfaces for the if e1 device driver 3 Declares the external timeval data structure called time Various ioctl commands use this data structure Network Device Driver Environment 1 5 Declares a pointer to the external task_t data structure called first task Thetask_t data structure is an opaque data structure that is all of its associated members are referenced and manipulated by the Tru64 UNIX operating system and not by the user of kernel threads Every kernel thread must be part of a task Theif_eldriver s el probe interface uses this data structure when it creates a kernel thread 1 2 2 Declaring softc and controller Data Structure Arrays The following code shows the declarations for the el_softc and controller data structure arrays The system uses these arrays to find out which s
77. c gt basereg reg 3 1 Fillsin the rege member of the el_softc data structure for this 3Com 3C5x9 device The value that is stored in regE consists of the O handle plus a byte offset The el probe routine computes this address according to the requirements of the PCMCIA bus and the ISA bus 2 This lineand the subsequent lines compute and save other if e1 device register addresses in the el_softc data structure 3 Stores the I O handle in the basereg member of the el_softc data structure for this 3Com 3C5x9 device 5 1 8 Setting Bus Specific Data Structure Members 5 8 The following code shows how the e1_ probe routine sets members for the bus specific data structures that are associated with the PCMCIA and ISA buses See the bus specific manual for information on data structures for the bus on which your driver operates switch ctlr gt bus_hd gt bus type 1 case BUS _PCMCIA 2 Implementing the Autoconfiguration Support Section probe 10 11 12 sc gt irg 3 sc gt iobase 0 3 sc gt ispcemcia 1 5 sc gt cinfop card_infop pemcia_register_event_callback card_infop gt socket_vnum 6 CARD_REMOVAL_ EVENT caddr_t el_card_remove caddr_t sc if multi_func_ flag 7 lan_set_attribute sc
78. call is made only after the call toif_attach 2 Registers the adapter with EHM 6 10 Handling the Reinsert Operation If the user has reinserted the PCMCIA card the if _e1 device driver does not need to initialize the media address and media length It does not need to set up the media specify the network driver interfaces set the baud rate or initialize simple lock information These tasks are done during the first attach operation Theel_attach routine needs only to initialize the device as follows else printf el d s reloaded current lan address s n unit ifp gt if_version ether _sprintf sc gt is_addr 1 if ifp gt if_flags amp IFF_RUNNING 2 el_ init unit 1 If the adapter was reinserted calls the printf routine to display the following information on the console terminal e Thecontroller number which is stored in the unit variable e The version of the network interface which is stored in the if version member of the ifnet data structure e The hardware address of the device 2 Calls the driver s el_init routine if the resources that are associated with the network interface were previously allocated Implementing the Autoconfiguration Support Section attach 6 9 6 11 Enabling the Interrupt Handler The following code shows how the el_attach routine enables the interrupt handler handler _enable
79. ce has been probed calls the lan_create_controller routine to try to create a second controller data structure If lan_create_ controller fails calls the printf routine to display a message Routines that begin with lan_ reside in the lan_common c source file 5 16 Implementing the Autoconfiguration Support Section probe 5 1 14 Registering the shutdown Routine The following code shows how the e1_probe routine registers its shutdown routine The kernel calls this routine when the system shuts down The driver can specify an argument for the kernel to pass to the routine at that time if sc gt reprobe drvr_register_shutdown el_ shutdown void sc DRVR_REGISTER 1 return 0 1 Registers the shutdown routine and directs the kernel to pass a pointer to the driver s softc data structure to the routine The shutdown routine is important for those devices that perform DMA related operations 5 2 Implementing the el_shutdown Routine The driver s shutdown routine shuts down the controller The kernel calls all registered shutdown routines when the system shuts down The el_probe routine registers a shutdown routine called el_shutdown The if_el device driver implements the routine as follows static void el_shutdown struct el_softc sc 1 WRITE _CMD sc CMD RESET 2 DELAY 1000 3 Specifies th
80. cedriver s el_softc data structure Make sure that the interrupt handler ID part of your softc data structure has a similar declaration ihandler id t hid 1 1 Declares a pointer to an ID that deregisters the interrupt handlers 3 7 Defining CSR Pointer Information The control and status register CSR addresses in a network driver s softc data structure consist of specific adapter register addresses These registers generally consist of the base register plus some offset as defined by the network adapter s hardware specification Make sure that you neve 3 6 Defining the softc Data Structure access a CSR directly The driver specific macros handle the read and write operations that are made on these device registers The following code shows the declarations of the CSR addresses inthe if el device driver s el _softc data structure Make sure that the CSR pointer information part of your softc data structure has similar declarations io_handle t regE 1 io_handle t regC io_handle t regA io_handle t reg8 io_handle t reg6 io_handle t reg4 io_handle t reg2 io_handle t reg0 io_handle t data Declares the CSR addresses for the if _e1 driver These addresses are computed during the probe routine by adding the specified offset OxE OxC OxA and so forth to the base address 3 8 Defining FIFO Maintenance Information The first in first out FIFO maintena
81. ceeeee eens teat ees 13 1 7 Releasing the Simple Lock and Resetting the IPL 13 1 8 Indicating That the Interrupt Was Serviced 5 13 2 Implementing the el_rint Routine cece cece eee 13 2 1 Counting the Receive Interrupt and Reading the Receive SEALUS anr F 2 cer tame ete ee a aaa A rena cata aes 13 2 2 Pulling the Packets from the FIFO Buffer 13 2 3 Examining the First Part of the Packet 0 005 13 2 4 Copying the Received Packet into the mbuf 13 2 5 Discarding a Packet c cece eect eee eee eee tee eta 13 3 Implementing the el_tint Routine cece cece eee eee 13 3 1 Counting the Transmit Interrupt eeeeee eee eee 13 3 2 Reading the Transmit Status and Counting All Significant EVONUS ea eea mia eta ca a N ERTAINE EE EE 13 3 3 Managing Excessive Data Collisions ssesssrerrrrrse 13 3 4 Writing to the Status Register to Obtain the Next Value 13 3 5 Queuing Other Transmits cccce eee cree 13 4 Implementing the el_error Routine cceeeeee eee ees 14 Network Device Driver Configuration Index Figures 1 1 Sections of a Network Device Driver ccccee cece eee 2 1 Window 0 Configuration Registers cceeeeeeeee teat ees 2 2 Window 3 Configuration Registers cceeeeeeeee teas ees 2 3 Window 1 Operational Registers ceeeeeeeeee teat ees
82. cket Section 13 2 5 13 2 1 Counting the Receive Interrupt and Reading the Receive Status The following code shows how the el_rint routine counts the receive interrupt and reads the receive status define RXLOOP 16 1024 64 1 static void el_rint struct el_softc sc struct ifnet ifp int len i count RXLOOP volatile short status struct mbuf m unsigned char dat unsigned int in struct ether header eh sc gt rint 2 status READ RXS sc 3 Defines a constant that represents the maximum number of packets in a 16K receive buffer Increments the receive interrupt counter Calls the READ _RXS macro to read the receive status Implementing the Interrupt Section 13 5 13 2 2 Pulling the Packets from the FIFO Buffer The following code shows how the el_rint routine pulls the packets from the first in first out FIFO buffer This task is specific to the hardware device that is associated with the if _e1 device driver If you need to perform a similar task with your hardware device use this example as a model while status gt 0 amp amp count gt 0 2 len status amp RX_BYTES if status amp RX_ER len gt 1518 len lt 60 2 if status amp RX_ER 3 status amp RX_EM if sc gt ctrblk est_recvfail l Oxffff sc gt ctrblk est_recvfail switch status case RX_EOR 4
83. ctl Commands The SIOCRDCTRS ioct1 command returns the values of network counters Thedriver s softc data structurestores a pointer tothe counter information The driver returns the information to the caller in a ct rreg data structure which is passed into the ioct1 routine through the data argument The SIOCRDZCTRS ioctl command also zeroes the network counters The following code shows how the el_ioct1 routine implements the SIOCRDCTRS and SIOCRDZCTRS ioctl commands case SIOCRDCTRS 1 case SIOCRDZCTRS ctr gt ctr_ether sc gt ctrblk 2 ctr gt ctr_type CTR_ETHER 3 ctr gt ctr_ether est_seconds time tv_sec sc gt ztime gt Oxfffe Oxffff time tv_sec sc gt ztime 4 if cmd SIOocRDzcTRS 5 sc gt ztime time tv_sec bzero amp sc gt ctrblk sizeof struct estat break 1 Determines whether the cmd argument is SIOCRDCTRS or SIOCRDZCTRS Implementing the ioctl Section 12 11 o d gt amp N Copies the current counters to the ctrreq data structure Indicates that these are Ethernet counters Returns the number of seconds since the counters were last zeroed If the user process requested the SIOCRDZCTRS command zeroes the counters and sets the ztime member of the softc data structure tothe current time This indicates when the counters were zeroed For other types of net
84. d NULL Disables and deletes the interrupt handler The argument that is supplied to each function is the handler ID that was returned by handler_addintheel_probe routine 7 5 Terminating the Autosense Kernel Thread The following code shows how the el_unattach routine terminates the autosense kernel thread if sc gt autosense_thread 1 thread_force_terminate sc gt autosense_ thread sc gt autosense thread NULL Terminates the autosense kernel thread Implementing the unattach Routine 7 3 7 6 Unregistering the PCMCIA Event Callback Routine The following code shows how the el_unattach routine unregisters the PCMCIA event callback routine if sc gt ispcmcia 1 pemcia_unregister_event_callback sc gt cinfop gt socket_vnum CARD REMOVAL EVENT caddr_t el_card_remove For PCMCIA versions of the card directs the bus code not to return notification if the card has been removed 7 7 Stopping the Polling Process The following code shows how the el_unattach routine stops the polling process s splimp simple lock amp sc gt el_softc_lock if el_polling amp amp sc gt polling flag 1 untimeout void el_intr void ifp gt if_unit 2 sc gt polling flag 0 3 simple unlock amp sc gt el_softc_lock splx s 1 Stops the polling process if polling
85. disable and handler enable The hid member of the el_softc data structure stores this key 9 If the return value from handler _add equals NULL theif _e1 driver failed to register an interrupt handler for the if e1 device Thisisa fatal error and the if _e1 driver will undo all previous operations and return an error to the caller 5 1 12 Saving the controller and softc Data Structure Pointers The following code shows how the el_probe routine saves the controller andel_softc data structure pointers All probe interfaces perform this task el_softc unit sc 1 el_info unit ctlr 2 1 Saves the el_softc data structure pointer for this instance of the 3Com 3C5x9 device in the array of el _softc data structures The unit number is the offset to the data structure within the el_softc array 2 Saves the controller data structure pointer for this instance of the 3Com 3C5x9 device in the array of controller data structures 5 1 13 Trying to Allocate Another controller Data Structure The following code shows how the el_probe routine attempts to allocate another controller data structure You make this call so that a driver can support multiple devices if sc gt reprobe amp amp lan_create_controller amp el_ data ESUCCESS 1 printf el sd WARNING create _controller failed n unit 1 If this is the first time that the devi
86. e argument that the kernel passes to the routine which isa pointer to the driver s e1_softc data structure The driver specifies this argument when it registers the shutdown routinein its probe interface 2 Calls the WRITE CMD macro to write data to the command port register In this call the el_softc data structure for this 3Com 3C5x9 device contains the I O handle to reference the device s command register The data to be written is the CMD_RESET bit which resets the device 3 Calls the DELAY macro to delay the execution of el _shutdown for 1 millisecond before continuing execution This gives the reset command time to complete 5 3 Implementing the el_autosense_thread Routine The if_el device driver implements a driver specific routine called el_autosense thread to determine the mode of the network interface Theel_ probe routinecalls el autosense thread during device autoconfiguration Implementing the Autoconfiguration Support Section probe 5 17 To determine the mode el _autosense thread tries to send a test data packet in each of the possible modes When it successfully transmits the data packet it sets the network interface to that mode The 1m_media_mode lm media and 1m_media_state members of theel_softc data structure keep track of the progress of the autosensing procedure as follows The value of the 1lm_media_mode member determines whether the el_autosense thread will aut
87. e bitwise inclusive OR of the interrupt request IRQ stored in the irq member of the el_softc data structure and the reserved bit for the resource configuration register RCR_RSV 8 2 4 Ensuring That the 10Base2 Transceiver Is Off The following code shows how the el_init locked routine ensures that the 10Base2 transceiver is off This task is specific to the 3Com 3C5x9 device You may want to perform similar initialization tasks for the hardware device that your network driver controls WRITE _CMD sc CMD STOP2 1 DELAY 800 2 1 Calls the WRITE CMD macro to write data to the command port register The data to be written is the stop 10Base2 command bit CMD_STOP2 2 Calls the DELAY macro to wait 800 microseconds before continuing execution Implementing the Initialization Section 8 5 8 2 5 Setting the LAN Media The following code shows how the el_init locked routine sets the LAN media This task is specific to the 3Com 3C5x9 device You may want to perform similar initialization tasks for the hardware device that your network driver controls i READ ACR sc 1 i amp ACR BASE ACR OB2 L2 switch sc gt lm media 3 case LAN MEDIA BNC 4 WRITE _ACR sc i ACR_10B2 sc gt iobase 5 WRITE _CMD sc CMD _START2 6 DELAY 800 7 break case LAN MEDIA AUI 8 WRITE _ACR sc i ACR_10B5 sc gt iobase 9
88. e cfgmgr framework stores the style of interrupt processing for the Polling attribute The cf gmgr framework obtains this value from the etc sysconfigtab database gt Declares an integer variable called el _pollint and initializes it tothe value 16 The el _pollint variable is where the cf gmgr framework stores the polls per second for the Polls Per Second attribute The cfgmgr framework obtains this value from the etc sysconfigtab database o Declares an integer variable called el_ configured and initializes it to the value 0 zero The driver must increment this variable for each successfully configured e1 device 4 2 Implementing the Configure Section 12 Declares the lan config data structure which contains all information specific to the e1 driver The lan _configure common code uses this structure Declares an array of cfg_subsys_attr_t data structures and calls itel_attributes Describes the PCMCIA_Option attribute which specifies the option data for the PCMCIA bus Describes the ISA_Option attribute which specifies the option data for the ISA bus Describes the Polling attribute which is specific to this device driver It indicates the style of interrupt processing The operation code specifies CFG_OP_ CONFIGURE and CFG_OP_QUERY This means that the attribute can only be set at configuration time and after that o
89. e driver specific macros Table 1 1 Driver Specific Macros Macro Description READ_CCR and WRITE_CCR Read from and write to the 3Com 3C5x9 device s configuration control register READ _ACR and WRITE _ACR Read from and write to the 3Com 3C5x9 device s address control register WRITE _RCR Write to the 3Com 3C5x9 device s resource configuration register WRITE _ECR Write to the 3Com 3C5x9 device s EEPROM command register READ _EDR Read from the 3Com 3C5x9 device s EEPROM data register WRITE _CMD Write to the 3Com 3C5x9 device s command port registers READ_STS Read from the 3Com 3C5x9 device s I O status register READ DATA and Read from and write to the 3Com 3C5x9 device s WRITE DATA receive data and transmit data registers READ _ND and WRITE_ND Read from and write to the 3Com 3C5x9 device s network diagnostic register READ MD and WRITE_MD Read from and write to the 3Com 3C5x9 device s media type and status register READ TXF and READ RXF_ Read from the 3Com 3C5x9 device s transmit and receive FIFO registers WRITE_AD1 WRITE_AD2 Set the LAN physical address for the 3Com 3C5x9 and WRITE AD3 device READ _TXS and WRITE _TXS_ Read from and write to the 3Com 3C5x9 device s transmit status register Network Device Driver Environment 1 9 Table 1 1 Driver Specific Macros cont Macro Description READ_RXS Read from the 3Com 3C5x9 device s receive status register READ_FDP Read from t
90. e el_attach routine attaches to the packet filter and the network layer attachpfilter amp sc gt is_ed 1 if_attach ifp 2 el_ configured 3 Calls the attachpfilter routine to inform the packet filter driver about this network driver The attachpfilter routine is passed a pointer tothe ether driver data structure for this network device driver 6 8 Implementing the Autoconfiguration Support Section attach 2 Callsthe if _attach routine to attach an interface to the list of active interfaces The argument tothe if attach routineisa pointer to the ifnet data structure for with this device 3 If the probe and attach operations were successful increments the number of successfully configured e1 devices You must do this if you are using lan_configure 6 9 Setting Network Attributes and Registering the Adapter The following code shows how the if_attach routine sets the known nonzero network attributes for the enhanced hardware management EHM facility and registers the adapter lan_set_common_attributes sc gt ehm current_val amp sc gt is_ed 1 lan_set_attribute sc gt ehm current_val NET METHOD NDX net_method_automatic lan_register_adapter amp sc gt ehm ctlr 2 1 Sets any known nonzero network attributes for the enhanced hardware management facility Make sure that this function
91. e flags structure member 2 Callstheel init locked routine See Section 8 2 for a description of the el init locked routine 11 2 Implementing the Reset Section 12 Implementing the ioctl Section Theioctl section of a network device driver contains the code that implements a network device driver s ioct1 interface The ioct1 interface performs miscellaneous tasks that have nothing to do with data packet transmission and reception Typically it turns specific features of the hardware on or off Theel_ioct1 routine performs the following tasks e Determines whether the user has removed the PCMCIA card from the slot Section 12 2 e Sets the IPL and obtains the simple lock Section 12 3 e Recognizes the ioct1 command and performs the appropriate operations Table 12 1 lists the ioct 1 commands that network device drivers must recognize e Releases the simple lock and resets the IPL Section 12 17 Table 12 1 Network ioctl Commands ioctl Command Required Description For More Information SIOCENABLBACK No Enables loopback Section 12 4 mode SIOCDISABLBACK No Disables loopback Section 12 5 mode SIOCRPHYSADDR Yes Returns the current Section 12 6 and default MAC addresses SIOCSPHYSADDR Yes Sets the local MAC Section 12 7 address SIOCADDMULTI Yes Adds the devicetoa Section 12 8 multicast group SIOCDELMULTI Yes Removes the device Section 12 9 from a multicast group SIOCRDCTRS Yes Read
92. e if_e1 driver uses a simple lock to protect the data integrity of the el_softc data structure on multiprocessor systems It also guarantees the sequence of register accesses that a CPU in a multiprocessor system makes to the adapter See Writing Kerna Modules for more information about locking in an SMP environment The following code shows the declaration of the simple lock data structure intheif_el driver s el_softc data structure decl_simple_ lock data el_softc_lock 1 Uses the decl_simple_lock_data routine to declare a simple lock data structure as a member of the el_softc data structure Thesimple lock data structureis called el softc lock 3 10 Defining the softc Data Structure 4 Implementing the Configure Section The configure section of a network device driver contains the code that incorporates the device driver into the kernel either statically or dynamically In a static configuration the device driver s configure interface registers callback routines which allow the cf gmgr framework to configure the driver into the kernel at a specified point during system startup In a dynamic configuration the configure interface cooperates with the cfgmgr framework to handle user level requests to dynamically configure reconfigure and query a network device driver at run time Because these tasks are common to all network drivers the code has been consolidated into a single routine called l
93. eceiver Again Setting the LAN Address ccccceeee eee e eect teeta Processing Special FlaQS cceeeee ee ee tenet eee eae eee Setting the Debug Flag c cece eect cnet ee eee eens Enabling TX and RX cccecee cece eee eee eee ee eae eed Enabling Interrupts c cece cece eee cece eee eee eae eed Setting the Operational Window cceeeee eae Marking the Device aS RUNNING 2 ce eee cece e eee eee eee Starting the Autosense Kernel Thread 00cceeeees Starting the Transmit of Pending Packets 45 9 Implementing the Start Section 9 1 9 1 1 9 1 2 9 1 3 9 2 9 2 1 9 2 2 vi Contents Implementing the el_ start Routine cece e eee eee eee Setting the IPL and Obtaining the Simple Lock Calling the el_start_locked Routine ecceeeeee eee Releasing the Simple Lock and Resetting the IPL Implementing the el_start_locked Routine eeeeee Discarding All Transmits After the User Removes the PEMGIA Cardi socrii enart it ye Sebie seid ekese Peete Removing Packets from the Pending Queue and Preparing the Transmit Buffer ccc ceee eect eee eect eee etna eee ee eee po Lt ot ot bt p dd RWWWWP o CO CO CO CO CO CO CO CW WO WO WO l OOODOODOAWAAONNNDAA HE o re i MMe A O O O O bbh a
94. ed to the bus on which your network driver operates See the bus specific manual for information on data structures for that bus switch ctlr gt bus_hd gt bus type 1 case BUS _PCMCIA 2 reg io_handle card_infop gt io_addr 0 3 multi _func_flag card_infop gt card_option gt multi_func_flag 4 if multi_func_flag if READ BUS D16 reg WO MID ox6da50 5 WRITE BUS _D16 reg CMD PORT CMD RESET DELAY 1000 if READ BUS D16 reg WO MID ox6ds50 6 printf el d EtherLink III not found on bus n unit return 0 7 break 5 4 Implementing the Autoconfiguration Support Section probe case BUS_ISA 8 if get_config ctlr RES PORT NULL amp port_sel 0 gt 0 9 reg port_sel base_address 10 else 11 printf el d Can t get assigned IOBASE n unit return 0 if get_config ctlr RES_IRQ NULL amp irq_sel 0 lt 0 12 printf el d Can t get assigned IRQ n unit return 0 if el_isa_reset 0 13 el_isa_reset_all reg amp isatag ctir if el_isa_activate reg amp isatag ctlr 14 printf el d 3C509 not present or not responding at 0x x n unit reg return 0 break default L15 printf el d Unrecog
95. eis the device register header file for the if el device driver It defines the device register offsets for the 3Com 3C5x9 series Ethernet adapter Specifically the if elreg h file contains the following categories of device registers e Interrupt and status register Section 2 1 e Command port registers Section 2 2 e Window 0 configuration registers Section 2 3 e Window 3 configuration registers Section 2 4 e Window 1 operational registers Section 2 5 e Window 4 diagnostic registers Section 2 6 e EEPROM data structure definition Section 2 7 Your network device might have different device registers However this device register header file can serve as an example of how to set up device register offset definitions See your network device documentation to learn about control and status registers for your device 2 1 Interrupt and Status Register Offset Definitions The following code shows the offset definitions for the interrupt and status register The if e1 device driver reads these offsets from the interrupt and status register The CMD _ACKINT CMD_SINTMASK and CMD_ZINTMASK commands either set or clear the bits define STS PORT oxe 1 define S_IL define S_AF define S_TC define S_TA define S_RC define S_RE define S_IR define S US define S_ IP define CURWINDOW x 00 1 OV OT jw 1 lt lt 12 10 x gt gt 13 amp 0x7 11
96. ength segments Stores the next memory buffer in the chain of mbuf data structures in thems mbuf pointer The m_next member stores the next memory buffer in the chain Network device drivers typically reference this member through the alternate name m_next which is defined in the mbuf h header file If this is a zero length transmit calls them_freem routine to free the mbuf buffer chain Stores the first memory buffer in the chain of mbuf data structures in the mp mbuf pointer Stores the next memory buffer in the chain of mbuf data structures in the mn mbuf pointer Stores the amount of data in the mp mbuf in the len variable The mh_len member of the mbuf data structure pointer stores the amount of data in this mbuf data structure Network device drivers typically reference this member through the alternate name m_len which is defined in the mbuf h header file While the mn mbuf is not NULL manipulates the mh_len and mh_next members of the mbuf data structure to eliminate any zero length buffers Implementing the Start Section 9 5 in the middle The mfree routine is called to free any zero length memory buffers 12 Otherwise adds the length and sets the next memory buffer in the chain to the mp mbuf pointer 9 2 3 Transmitting the Buffer The following code shows how the el_start_locked routine transmits the buffer WRITE DATA sc len TX_INT 1 dat mtod ms unsigned char len ms gt m
97. equested network speed for the SIOCMACSPEED command Declares an mclist buf buffer which holds a character string This string is a list of all multicast addresses currently in use on the device 12 2 Determining Whether the User Has Removed the PCMCIA Card from the Slot The following code shows how the el_ioct1 routine determines whether the user has removed the PCMCIA card from the slot if sc gt cardout return EIO 1 Examines the value of the cardout member of the el_softc data structure for this device If it is set to 1 true the user has removed the PCMCIA card from the slot and the driver returns the EIO error constant to indicate an O error 12 3 Setting the IPL and Obtaining the Simple Lock The following code shows how the el_ioct1 routine sets theIPL and obtains the simple lock s splimp A simple _lock amp sc gt el_softc_lock 2 Calls the splimp routine to mask all LAN hardware interrupts On successful completion splimp stores an integer valuein the s variable that represents the CPU priority level that existed before the call to splimp Calls the simple _lock routine to assert a lock with exclusive access for the resource that is associated with el_softc_lock This means that no other kernel thread can gain access to the locked resource until Implementing the ioctl Section 12 3 12 4 12 5 12 4
98. er was implemented according to the specifications detailed in Etherne II Paralld Tasking ISA EISA Micro Channd and PCMCIA Adapter Drivers Technical Reference This specification is published by 3Com Corporation and the manual part number is 09 0398 002B You can access the if __e1 source code in the device driver examples directory if you have installed it on your system Ethernet is the network interface type that is associated with the if e1 driver However the explanations point out where differences exist between Ethernet and other network interfaces including fiber distributed data interface F DDI and Token Ring The example network driver operates on multiple buses specifically the PCMCIA bus and the ISA bus It uses the common ifnet interface to communicate with the upper layers of the Tru64 UNIX operating system The example does not emphasize any specific types of network device drivers However mastering the concepts presented in this manual is useful preparation for writing network device drivers that operate on a variety of buses The manual does not discuss e Howto write STREAMS network device drivers e Topics associated with wide area networks WANs e How towrite an asynchronous transfer mode ATM device driver e Details related to the network programming environment xii About This Manual New and Changed Features This revision of the manual documents the following new features e Enabling support for e
99. er of the softc data structure for this device to the constant ARPHRD_ETHER which represents the Ethernet hardware address The if_arp h file defines this constant For the Token Ring interface set the ac_arphrd member tothe constant ARPHRD_ 802 The if_arp h file also defines this constant For the FDDI interface set the ac_arphrd member to the constant ARPHRD_ETHER which represents the Ethernet hardware address See RFC 826 for more details Implementing the Autoconfiguration Support Section attach 6 3 3 Sets the if_mtu member of the ifnet data structure for this device to the maximum transmission unit which for Ethernet related media is represented by the constant ETHERMTU The following media specific constants represent the maximum transmission unit ETHERMTU The maximum transmission unit for Ethernet media The if _ether h file defines the ETHERMTU constant FDDIMTU The maximum transmission unit for FDDI media The if_fddi h file defines the FDDIMTU constant TRN4 RFC1042 IP MTU The maximum transmission unit for the 4 megabit per second Token Ring media The if_trn h file defines the TRN4 RFC1042 IP MTU constant TRN16_RFC1042 IP MTU The maximum transmission unit for the 16 megabit per second Token Ring media The if_trn h file defines the TRN16 RFC1042 IP MTU constant 4 Sets theif mediamtu member of the ifnet data structure for this device to the maximum transmission un
100. es FIFO loopback Indicates that TX is enabled Indicates that RX is enabled Indicates that TX is busy Indicates that TX reset is required Indicates that statistics are enabled Indicates the ASIC revision Not currently used 2 12 Defining Device Register Offsets 2 EEPROM Data Structure Definition The following code shows the definition for the w3_ eeprom data structure This data structure stores information about the 3Com 3C5x9 device struct w3_ eeprom 1 unsigned short addr 3 unsigned short pid unsigned short mandata 3 unsigned short mid unsigned short addrconf unsigned short resconf unsigned short oem 3 unsigned short swinfo unsigned short compat s s s ay s s s s unsigned short cs1 unsigned short cw2 unsigned short resl unsigned int icw unsigned short swinfo2 unsigned short res 2 unsigned short cs2 unsigned short pnp 40 1 Defines an EEPROM data structure called w3_ eeprom This data structure has the following members addr Contains the local area network LAN address pid Contains the product ID mandata Contains manufacturing data mid Contains the manufacturer ID addrconf Contains the address configuration resconft Contains the resource configuration oem Contains original equipment manufacturer OEM address fields swinfo Contains software information compat Contains a compatibility word csl Contains the first part of the
101. flags amp IFF_ LOOPBACK if ifp gt if_flags amp IFF_RUNNING el_reset_locked sc ifp unit break N w 1 Determines whether the cmd argument is SIOCDISABLBACK 2 Clears the IFF_LOOPBACK bit inthe if flags member of the ifnet data structure for this device 3 If the device is running calls the el_reset_locked routine Theel_reset_locked routinecalls el_init locked which restarts the network interface in normal mode Implementing the ioctl Section 12 6 Reading Current and Default MAC Addresses SIOCRPHYSADDR ioctl Command The following code shows how the el_ioct1 routine implements the SIOCRPHYSADDR ioctl command to read the current and default MAC addresses when an application requests them case SIOCRPHYSADDR 1 bcopy sc gt is_addr ifd gt current_pa 6 2 for i 0 i lt 3 i 3 j sc gt eeprom addr i ifd gt default_pa i 2 j gt gt 8 amp Oxff ifd gt default_pa i 2 1 j amp Oxff break 1 Determines whether the cmd argument is SIOCRPHYSADDR 2 Copies the current MAC address that is stored in the el_softc data structure for this device to the ifd data structure a command specific data structure of type ifdevea 3 Copies the default MAC address that is stored in the driver s el_softc data structure for this device to the ifd data structure
102. gn one of the following values to CMD_ FILTER RF_IND Individual address RF_GRP Group address RF_BRD Broadcast address RF_ PRM Promiscuous address Defines the receive RX early threshold command Defines the transmit TX available threshold command Defines the transmit TX start threshold command Defines the statistics enable command Defines the statistics disable command Defines the stop 10Base2 Ethernet cable command Defines the receive RX reclaim threshold command Defines the power up command Defines the power down command Defines the power auto command 2 3 Window 0 Configuration Register Offset Definitions The window 0 configuration registers include such registers as manufacturer ID and adapter ID as shown in Figure 2 1 2 4 Defining Device Register Offsets Figure 2 1 Window 0 Configuration Registers Manufacturer ID Register WO_MID Adapter ID Register WO_AID Configuration Control Register WO0_CCR ZK 1267U Al The following code shows the offset definitions for the registers that make up the window 0 configuration register define WO_MID oxo 1 define WO_AID 0x2 2 define WO_CCR 0x4 3 enum w0_ccr 4 CCR_PCMCIA 0x4000 CCR_AUI 0x2000 CCR_10B2 0x1000 CCR_ENDEC 0x0100 CCR_RESET 0x4 CCR_ENA 0x1 i define WO_ACR 0x6 5 enum w0_acr 6 ACR_10BT 0x0000 ACR_10B5 0x4000 ACR_10B2 0xc000 ACR_ROMS 0x3000 ACR_ROMB 0x0f00 ACR_ASE 0x0080 AC
103. gt ehm current_val NET_MODEL NDX 3C562 else lan_set_attribute sc gt ehm current_val NET_MODEL NDX 3C589 break case BUS_ISA 8 sc gt irg irq _sel channel 9 sc gt isa_tag isatag 10 sc gt iobase reg 0x200 0x10 amp 0x1f 11 lan_set_attribute sc gt ehm current_val NET _MODEL NDX 3C509 12 break Evaluates the bus_type member of the bus data structure for this 3Com 3C5x9 device Performs tasks that are related to the PCMCIA bus if bus_ type evaluates to BUS_PCMCIA Sets the interrupt request IRQ to the value 3 Sets the I O base of the program card to the value 0 zero Indicates that this is a PCMCIA unit and saves the card information pointer Calls the pemcia_register event callback routine See the if_el source file in the examples directory that is installed with the device driver kit for a listing of this routine Sets the model identification attribute for enhanced hardware management support Performs tasks that are related to the ISA bus Saves the interrupt request IRQ from the ISA bus configuration code Saves the tag from the activation process Computes the I O base to give to the device Sets the model identification attribute for enhanced hardware management support Implementing the Autoconfiguration Support Section probe 5 9 5 1 9 Handling First Time Probe Operations If the device has not alre
104. he 3Com 3C5x9 device s FIFO diagnostic port register 1 3 Configure Section for a Network Driver The configure section for a network device driver contains a configure interface The cf gmgr framework calls the driver s configure interface at system startup to handle static configuration requests The cf gmgr framework can also call the driver s configure interface to handle user level requests to dynamically configure unconfigure query and reconfigure a device driver at run time If you implement the driver as a single binary module the configure interface can handle both static and dynamic configuration 1 4 Autoconfiguration Support Section for a Network Driver The autoconfiguration support section for a network device driver contains the following entry points e A probe interface which determines if the network device exists and is functional on the system e AN attach interface which establishes communication with the device and initializes the driver s ifnet data structure You define the entry point for each of these interfaces in the driver data structure 1 5 Initialization Section for a Network Driver The initialization section for a network device driver prepares the network to transmit and receive data packets 1 6 Start Section for a Network Driver The start section for a network device driver contains a start interface which transmits data packets on the network interface You define the entry p
105. he Autoconfiguration Support Section probe e Determines whether packets were transmitted successfully Section 5 3 14 e Prints debug information Section 5 3 15 e Sets up new media totry if transmit was unsuccessful Section 5 3 16 e Establishes media if transmit was successful Section 5 3 17 5 3 1 Setting Up the el_autosense_thread Routine The following code shows how to set up the el_autosense thread routine unsigned char el_junk_msg 4 Oxaa Ox00 0x04 Oxff Oxff Oxff 0 0 0 O O O Ox60 Ox06 A Da ogee S S 1 Rm at Cc A a SR RO CRS CS E Sim ME ie e Se a ol ORE Yale A SRP E 9 OPS TA A E E Ceri GS pe ety Raha ap Ot Cr ya i define EL JUNK SIZE 46 define EL_AUTOSENSE PASSES 3 10 static void el_autosense thread struct el_softc sc 2 struct ifnet ifp amp sc gt is_ if 3 unsigned long prev_tint prev_tmo prev_err struct mbuf m int good_xmits wait s i link_beat passes unsigned long wait_flag 0 Defines the message to transmit when trying to determine the mode of the device 2 Declares a pointer totheel_ softc data structure and calls it sc 3 Declares a pointer toan ifnet data structure and calls it ifp This line also initializes ifp to the address of the ifnet data structure for this 3Com 3C5x9 device The ifnet data structure is referenced through theis if member of theel_softc data structure pointer
106. he driver module and to set device attributes The information that you provide in the sysconfigtab file fragment depends on the bus on which the driver operates The following sysconfigtab file fragment entries are bus specific e PCI Option The PCI_Option entry specifies the option data that is associated with the PCI bus See Writing PCI Bus DeviceDrivers for a description of the values that you can specify with this entry e VBA Option The VBA_Option entry specifies the option data that is associated with the VMEbus See Writing VME bus DeviceDrivers for a description of the values that you can specify with this entry For moreinformation on the sysconfigtab file fragment as well as how to build and either statically or dynamically link your driver see Writing Kerna Modules Network Device Driver Configuration 14 1 Numbers and Special Characters Index C 10Base2 transceiver ensuring that it is off 8 5 A allocating the ether_driver data structure 5 7 attach interface 6 1 registering adapters 6 9 setting network attributes 6 9 autoconfiguration attach interface 6 1 probe interface 5 1 autoconfiguration support section 1 10 5 1 implementing 6 1 autosense thread context information 3 9 autosensethread starting 8 11 carrier checking for transmits 5 23 cfg_subsys_attr_t data structure 4 2 command port register definitions 2 2 common information el_softc data structure 3 2 comput
107. imple lock and resets the IPL The following code shows how this is done static void el_reset int unit struct l softo sc el_softc unit struct ifnet ifp amp sc gt is_if int s if sc gt cardout return 1 s splimp 2 simple _lock sc gt el_softc_lock el_reset_locked sc ifp unit L3 simple _unlock sc gt el_softc_lock 4 splx s 1 If the user has removed the PCMCIA card from the slot returns to the calling routine 2 Calls the splimp routine to mask all LAN hardware interrupts before obtaining the simple lock for the el_softc resource Implementing the Reset Section 11 1 3 Callstheel reset _locked routine which performs the actual tasks that are associated with resetting the device 4 Callsthe simple unlock routine to release the simple lock for the el_softc data structure and then resets the CPU priority to the level that it was originally at upon entrance to this routine 11 2 Implementing the el_reset_locked Routine The following code shows how the el_reset_locked routine resets and restarts the hardware static void el_reset_locked struct el_softc sc struct ifnet ifp int unit ifp gt if_flags amp IFF_RUNNING 1 el_init_locked sc ifp unit 2 1 Indicates that the device is no longer running by clearing the IFF_RUNNING bit in the interfac
108. ing code shows how the el_autosense thread routine selects new media totry if the transmit operation failed switch sc gt lm media 1 case LAN MEDIA AUI 5 24 Implementing the Autoconfiguration Support Section probe N if sc gt lm media_mode LAN MODE AUTOSENSE sc gt lm_media LAN MEDIA UTP break case LAN MEDIA BNC if sc gt lm_media_mode LAN MODE AUTOSENSE sc gt lm_media LAN MEDIA AUI break case LAN MEDIA UTP default if sc gt lm_media_mode LAN MODE AUTOSENSE sc gt lm_media LAN MEDIA BNC break el _ reset ifp gt if_unit 2 Selects new media Calls the el_ reset routine to reset the hardware This reset will establish the next media to try 5 3 17 Establishing the Media The following code shows how the el_autosense thread routine establishes the new media if sc gt debug if sc gt lm_media LAN MEDIA UTP amp amp link beat amp amp passes lt EL _AUTOSENSE PASSES printf el sd No Link Beat signal n ifp gt if_unit sc gt lm_media_state LAN MEDIA STATE DETERMINED 1 printf el sd Autosense selected s media n ifp gt if_unit lan_media_strings_10 sc gt lm_media s splimp 2 simple lock amp sc gt el_softc_lock 3 WRITE _CMD sc CMD _STATSDIS 4 simple unlock amp sc gt el_softc_lock 5 splx s 6
109. ing code shows how the el_intr routine transmits pending frames if ifp gt if_snd ifq head 1 el_start_locked sc ifp else ifp gt if_timer 0 2 1 Determines whether there are any transmits pending If So e1_intr calls el _ start locked to start the transmit operation 2 Otherwise disables the watchdog timer by setting the e1_ timer member of the ifnet data structure to 0 zero 13 1 7 Releasing the Simple Lock and Resetting the IPL The following code shows how theel_intr routine releases the simple lock and resets the IPL simple unlock amp sc gt el_softc_lock splx s 13 4 Implementing the Interrupt Section 13 1 8 Indicating That the Interrupt Was Serviced The following code shows how the el_intr routine indicates that the interrupt was serviced return INTR_SERVICED 1 Returns the INTR_SERVICED constant to the kernel interrupt dispatcher toindicate that el intr serviced the shared interrupt 13 2 Implementing the el_rint Routine Theif_el driver s el rint routineis the receive interrupt completion routine It performs the following tasks Counts the receive interrupt and reads the receive status Section 13 2 1 Pulls the packets from the FIFO buffer Section 13 2 2 Examines the first part of the packet Section 13 2 3 Copies the received packet into the mbuf Section 13 2 4 Discards a pa
110. ing the CSR addresses 5 8 configuration 14 1 configure interface 4 1 configure section 1 10 controller data structure allocating multiple 5 16 array declaration 1 6 saving pointer 5 16 counter reading 12 8 updating 9 7 CSR pointer information 3 7 D base register 3 6 baud rate setting 6 8 broadcast flag 3 8 buffer transmitting 9 6 bus specific information 3 7 initializing 5 8 data collision dealing with excessive 13 11 data structure cfg_subsys attr t 4 2 controller 5 16 driver 1 7 el_softc 1 6 5 6 5 8 5 16 simple lock 3 10 softc 3 1 w3_eeprom 2 13 3 10 data transfer Index 1 of pending transmit frames 13 4 SIOCADDMULTI ioctl command of receive interrupt 13 8 12 6 debug flag 3 8 SIOCDELMULTI ioctl command setting 8 9 12 7 debug information SIOCDISABLBACK ioctl command printing 5 24 12 4 declarations SIOCENABLBACK ioctl command configure related 4 2 12 4 network device driver 1 4 SIOCIFRESET ioctl command declarations section 1 4 12 11 devdriver h header file 1 4 SIOCIFSETCHAR ioctl command device 12 11 bringing up 12 9 SIOCRDCTRS ioctl command marking as running 8 10 12 8 resetting 11 2 12 11 SIOCRDZCTRS ioctl command setting characteristics 12 11 12 8 starting 8 5 SIOCRPHY SADDR ioctl command device physical address 12 5 reading and saving in first time SIOCSIFADDR ioctl command probe operation 5 10 12 9 i gerrea register SIOCSIFFLAGS ioctl command
111. ion about the lan_media data structure The following code shows the declaration and definition of the media state information in the if _e1 devicedriver s el_softc data structure struct lan media lan media 1 define lm media_mode lan_media lan_media_mode 2 define lm media_state lan_media lan_media_state 3 define lm media lan_media lan_media 4 1 Declares a lan_media data structure and calls it Lan_media The lan_media data structure contains media state values 2 Defines an alternate name for referencing the lan _media_mode member of the lan_media data structure The value that is stored in 3 4 Defining the softc Data Structure lan_media_mode usually reflects how the media is to be selected In contrast the value that is stored in the lan_media member reflects the current setting of the device Typically you set this member in the driver s probe interface to the media mode constant that identifies the mode for the media The 1lan_common h file defines two enumerated data types called media_types and media_modes You can set the lan_media_mode member to one of the following values which are defined by the media_types and media_modes enumerated data types LAN MEDIA UTP The mode for the media is unshielded twisted pair cable LAN MEDIA BNC The mode for the media is thin wire LAN MEDIA STP The mode for the medi
112. ion code passes this 1 O handle to the driver s probe interface during device autoconfiguration Declares a pointer toa controller data structure for this controller This data structure contains such information as the controller type the controller name and the current status of the controller The bus configuration code passes this initialized controller data structure to the driver s probe and attach interfaces A device driver typically uses the ct lr_num member of the controller data structure as an index to identify the instance of the controller a request is for Declares a pointer tothe el_softc data structure and calls it sc Declares a unit variable and initializes it to the controller number for this controller This controller number identifies the specific 3Com 3C5x9 controller that is being probed The controller number is 5 2 Implementing the Autoconfiguration Support Section probe contained in the ct1r_num member of the controller data structure for this 3Com 3C5x9 device Declares ahandler_intr_info data structure called el_intr_info Thehandler_intr_info data structure is a generic data structure that contains interrupt handler information for buses that are connected toa device controller Using the handler_intr_info data structure makes the driver more portable across different bus architectures Declares an ihandler_t data structure ca
113. ions of the tuple info andtuple data_info data structures see the usr sys include io dec pemcia cardinfo h file and tuple info andtuple data_info Implementing the Autoconfiguration Support Section probe 5 3 5 1 2 Checking the Maximum Number of Devices That the Driver Supports The following code shows how to check for the maximum number of devices that the if e1 device driver supports if unit gt el MAXDEV 4 printf el d el_probe unit exceeds max supported devices n unit return 0 2 1 If the unit variable exceeds the maximum number of devices that the if el driver supports calls the printf routine to display an appropriate message on the console terminal The printf routine also displays the controller number that is stored in the unit variable The el _probe routine stores the controller number in this variable by referencing the ct lr_num member of the controller data structure pointer The el MAXDEV constant defines the maximum number of controllers that the if _e1 driver can support 2 Returns the value 0 zero to indicate that the probe operation failed 5 1 3 Performing Bus Specific Tasks The following code shows how the el_probe routine performs tasks that are specific to the PCMCIA and ISA buses Only network device drivers that operate on the PCMCIA and ISA buses perform these tasks Your probe interface performs tasks that are relat
114. is data structure The cfg_attr_t data structure Implementing the Configure Section 4 3 4 4 represents a variety of information including the if _e1 driver s interrupt polling requirements Declares an argument called indatalen to store the size of this input data structure This argument represents the number of cfg _ attr _t data structures included in indata Declares an argument for user defined configuration operations which can occur when the cf gmgr framework calls the driver s configure interface with the CFG_OP_USERDEFINED operation code Typically this argument is not used Declares the size of the outdata argument Typically this argument is not used Calls the LAN common driver code to configure the device either statically or dynamically Implementing the Configure Section 5 Implementing the Autoconfiguration Support Section probe The autoconfiguration support section contains the code that implements a network device driver s probe interface A network device driver s probe interface determines whether the network device exists and is functional on a given system The bus configuration code calls the driver s probe interface Theif_el driver operates on the ISA and PCMCIA bus For the PCMCIA bus it provides a driver specific routine that is called when a user removes the card from the slot For the ISA bus the driver provides routines to reset activ
115. it for the media which for Ethernet related media is represented by the constant ETHERMTU Typically you set this member to the same constant that is used for the i _mtu member 5 Sets theif type member of the ifnet data structure for this device to the type of network interface which is represented by the constant IFT_ETHER Ethernet or II interface The following describes some of the valid interface types that are defined in the if _types h file IFT_ETHER Ethernet or II interface IFT _FDDI FDDI interface IFT_IS088025 Token Ring interface 6 Sets theac_ flag member of the arpcom data structure for this device to the value 0 zero This indicates that an IP address is currently not configured for this interface 7 Sets the sockaddr_in data structure pointer to the address of the network interface The address of the network interface is referenced through the if addr member of the ifnet data structure for this device 6 4 Implementing the Autoconfiguration Support Section attach Sets the sin_family member of the sockaddr_in data structure to the address family which in this case is represented by the constant AF_INET The socket h file defines this and other address family constants 6 4 Initializing Simple Lock Information The following code shows how the el_attach routine sets up simple lock information
116. itecture including interrupts direct memory access DMA operations and I O Before you write a network device driver we recommend that you be familiar with the networking subsystem that the Tru64 UNIX operating system provides This manual assumes that you are familiar with the following network interface types e Ethernet e Fiber Distributed Data Interface F DD e Token Ring See the Tru64 UNIX Technical Overview for descriptions of the data link media This manual also assumes that you have some knowledge of the Tru64 UNIX network programming environment particularly e Data link provider interface e X Open transport interface e Sockets About This Manual xi e Socket and XTI programming examples e TCP specific programming information e Information for Token Ring driver developers e Data link interface See the Tru64 UNIX Network Programmer s Guide for descriptions of these topics Scope of this Manual This manual builds on the concepts and topics that are presented in Writing Device Drivers which is the core manual for developing device drivers on Tru64 UNIX It introduces topics that are specific to writing a device driver for a local area network LAN device and that are beyond the scope of the core manual In this manual you can study a network driver called if _e1 Theif_el driver supports the driver interface requirements for a LAN device specifically the 3Com 3C589C series PCMCIA adapter The if _e1 driv
117. its priority degrades if it consumes an inordinate amount of CPU resources Make sure that your device driver calls kernel_thread_w_arg only for long running tasks and always attaches a kernel thread to the first task Thekernel_thread_w_arg routinereturns a pointer tothe thread data structure for the newly created thread The device driver stores this pointer inthe autosense_ thread member of the el_softc data structure If the valuethat kernel_thread_w_arg returnsis NULL then the thread could not be created At this point the el _probe routine must undo previous work and return a failure indication to the caller For PCMCIA versions of the card unregisters the callback routine that was previously registered Deallocates the ether_driver data structure for this device Frees up any memory that was allocated for enhanced hardware management and unregisters this card from the hardware management database Calls the FREE macro which frees the memory that was previously allocated for the el_softc data structure Returns the value 0 zero to indicate that the probe operation fail ed 5 1 10 Handling Subsequent Probe Operations If the device had already been probed the if e1 device driver reads the EEPROM to determine whether the hardware address has changed The following code shows how the e1_probe routine performs these tasks else struct w3_ eeprom ee _copy unsigned char tmp_addr 8 struct ifreq ifr struc
118. ivers typically include this file If you are writing the network driver for FDDI media you alsoindude the header file if fddi h If you are writing the network driver for Token Ring media you also include the header file if trn h Includes the devdriver h header file which defines common device driver data structures and constants The devdriver h fileis located in usr include io common devdriver h Includes the header file eisa h which is associated with the ISA bus If you are writing the driver to operate on multiple bus architectures you must include the bus specific header file The if e1 device driver is implemented to operate on two buses the ISA and the PCMCIA Includes the header files pcmcia h and cardinfo h which are associated with the PCMCIA bus Includes the lan_common h file which contains definitions that all local area network LAN device drivers need Includes the device register header file The directory specification you make here depends on where you put the device register header file 1 2 Declarations Section for a Network Driver The declarations section for a network device driver contains the following categories of information 1 4 Network Device Driver Environment e External and forward declarations Section 1 2 1 e Dediaration of softc and controller data structure arrays Section 1 2 2 e Declaration of the driver data structure Section 1 2 3 e Definitions of driver specific mac
119. k default break Tests for loss of carrier errors Most network adapters give carrier errors if no cableis plugged in or if transceivers are not present 5 3 14 Determining Whether Packets Were Transmitted Successfully The following code shows how the el_autosense thread routine determines whether packets were successfully transmitted if prev_err ifp gt if_oerrors amp amp prev_tmo sc gt xmit_tmo amp amp wait lt 5 2 good_xmits if sc gt debug printf el d autosense s packet sent OK d n ifp gt if_unit lan_media_strings_10 sc gt lm_media good_xmits else good_xmits 0 Determines whether traffic went out successfully 5 3 15 Printing Debug Information The following code shows how theel_autosense_ thread routine prints debug information if sc gt debug 4 if prev_err ifp gt if_oerrors printf el d autosense s transmit error n ifp gt if_unit lan_media_strings_10 sc gt lm_media if prev_tmo sc gt xmit_tmo printf el d autosense s driver transmit timeout n ifp gt if_unit lan_media_strings_10 sc gt lm_media if wait gt 5 amp amp wait lt 100 printf el d autosense s transmit timeout n ifp gt if_unit lan_media_strings_10 sc gt lm_media Prints debugging information if requested 5 3 16 Setting Up New Media The follow
120. k is no longer held 8 Ifan IP address was configured broadcasts an ARP packet to notify all hosts that currently have this address in their ARP tables to update their information 9 Notifies the network layer about a possible change in the af_ link address 12 8 Adding the Device to a Multicast Group SIOCADDMULTI ioctl Command The following code shows how the el_ioct1 routine implements the SIOCADDMULTI ioctl command to add a multicast address case SIOCADDMULTI 1 need_reset 0 if bemp ifr gt ifr_addr sa_data etherbroadcastaddr 6 0 2 sc gt is_broadcast else i lan_add_multi amp sc gt is_ multi unsigned char ifr gt ifr_addr sa_data switch i case LAN MULTI_CHANGED if sc gt is_multi lan_nmulti 1 L3 need_reset break case LAN MULTI NOT CHANGED break case LAN MULTI FAILED default status EINVAL break if ifp gt if_flags amp IFF_RUNNING amp amp need_reset 4 el_reset_locked sc ifp unit if sc gt debug j 0 printf el d Dump of multicast table after ADD d entries n unit sc gt is_multi lan_nmulti for i 0 i lt sc gt is_multi lan_nmulti i unsigned char maddr LAN GET MULTI amp sc gt is multi maddr j printf sd s muse d n i 1 12 6 Implementing the ioctl Section ether sprintf maddr sc gt is_ multi lan_mtable j 1
121. kernel thread ID 2 Contains the autosense kernel thread blocking flag 3 14 Defining the Polling Context Flag ALAN driver typically does not need to perform polling operations H owever the if el driver provides an example of how polling operations might be accomplished The polling context flag in a network driver s softc data structure indicates whether polling is on or off The following code shows the declaration of the polling member in the if e1 device driver s el _softc data structure int polling flag 1 Declares a polling context flag member called polling flag This member stores a boolean value of 1 polling context is on or O polling context is off Defining the softc Data Structure 3 9 3 15 Defining a Copy of the w3_eeprom Data Structure The w3_ eeprom data structure copy in the if el driver s el _softc data structure consists of information about the hardware specific w3 eeprom data structure The following code shows the declaration of this device specific data structure If your device has an EEPROM you might want to save some or all of its contents in your softc data structure struct w3_eeprom eeprom 1 1 Declares a copy of the w3_ eeprom data structure and calls it eeprom 3 16 Declaring the Simple Lock Data Structure A network driver s softc data structure contains the declaration of a simple lock data structure Th
122. l_configured i cfg_subsys_ attr_t el_attributes 7 PCMCIA Option CFG ATTR STRTYPE CFG OP CONFIGURE CFG OP QUERY Op a E iniit D caddr_t el_pcmcia_optiondata 0 400 0 L8 ISA Option CFG ATTR_STRTYPE CFG OP CONFIGURE CFG OP QUERY _OP a w VE Eo caddr_t el_isa_optiondata 0 300 0 L9 Polling CFG ATTR INTTYPE CFG OP QUERY CFG_OP_ CONFIGURE g i UP OFS caddr_t amp el_ polling 0 1 sizeof int 10 Polls Per Second CFG_ATTR_INTTYPE CFG OP _QUERY CFG OP CONFIGURE caddr_t amp el_pollint 10 100 sizeof int 11 0 0 0 0 0 0 12 Declares a character array called pcmcia _optiondata and initializes it tothe null string The pcmcia _optiondata character array is where the cf gmgr framework stores the value for the PCMCIA Option attribute The cf gmgr framework obtains this value from the etc sysconfigtab database N Declares a character array called isa_optiondata and initializes it tothe null string The isa_optiondata character array is where the cfgmgr framework stores the value for the ISA_Option attribute The cfgmgr framework obtains this value from the etc sysconfigtab database o Declares an integer variable called el polling and initializes it to the value 0 zero The el_ polling variable is where th
123. lled el_ihandle to contain information for the if _e1 device driver s interrupt service routine registration Declares a pointer toa card_info data structure called card_infop and initializes it to the specific card_info data structure for this controller This data structure is associated with PCMCIA devices only The bus configuration code passes this card_info data structure through the controller data structure s conn_priv 2 member The pemcia h file defines card_info_ptr as conn priv 2 Declares a variable called reg that stores the I O handle that is passed tothe driver s el_probe routine Declares an e_port data structure called port_sel This data structure is associated with the EISA and ISA buses Thee_port data structure describes bus I O port information The bus configuration code initializes the members of the e port data structure during device autoconfiguration Device drivers call the get_config routine to obtain information from the members of the e port data structure Declares an irq data structure called irq sel The irq data structure specifies EISA ISA bus interrupt channel characteristics that are assigned to a device The bus configuration code initializes the members of the irq data structure during device autoconfiguration Device drivers call the get_config routine to obtain information from the members of the irg data structure Declares the tuple_ data structures For more information and definit
124. llowing code shows how the el_watch routine counts the number of transmit timeouts clears the timer and resets the unit sc gt xmit tmo 1 ifp gt if_timer 0 el_reset_locked sc ifp unit L2 Increments the transmit timeout counter which stores the number of times transmit timeouts occur N Callstheel_reset_locked routine to reset the device 10 3 Releasing the Simple Lock and Resetting the IPL The following code shows how the el_watch routine releases the simple lock and resets the IPL simple_unlock amp sc gt el_softc_lock splx s return 0 10 2 Implementing a Watchdog Section 11 Implementing the Reset Section The reset section of a network device driver contains the code that resets the LAN adapter when thereis a network failure and there is a need to restart the device It resets all of the counters and local variables and can free up and reallocate all of the buffers that the network driver uses The if_el device driver implements the following routines in its reset section e el reset Section 11 1 e el reset _locked Section 11 2 11 1 Implementing the el_reset Routine Theel_ reset routineis a jacket routine that performs the following tasks e Determines whether the user removes the PCMCIA card from the slot e Sets thelPL and obtains the simple lock e Callstheel reset locked routine to reset the device e Releases the s
125. lx s L2 Calls the simple unlock routine to release a simple lock for the resource that is associated with the specified simple lock data structure Implementing the Start Section This simple lock was previously asserted by callingthesimple lock or simple _lock_try routine 2 Calls the sp1x routine toreset the CPU priority to the level that the s variable specifies 9 2 Implementing the el_start_locked Routine Theel_start_locked routine performs the start operation It is called by the if el devicedriver s el init locked el_start el_intr andel_ autosense thread routines Theel_start_locked routine performs the following tasks e Discards all transmits if the user has removed the PCMCIA card Section 9 2 1 e Removes packets from the pending queue and prepares the transmit buffer Section 9 2 2 e Transmits the packets Section 9 2 3 e Accounts for the outgoing bytes Section 9 2 4 e Updates counters frees the transmit buffer and marks the output process as active Section 9 2 5 e Indicates when to start the watchdog interface Section 9 2 6 Note If you decide not to implement your start section as a jacket routine then some of the tasks listed in this section would be performed by your start section 9 2 1 Discarding All Transmits After the User Removes the PCMCIA Card The following code shows how the el_ start locked routi
126. m data structure that stores the hardware address The if_ether h file defines the ac_enaddr alternate name Figure 3 2 shows the is_addr alternate name and associated mapping Defining the softc Data Structure 3 3 Figure 3 2 Mapping Alternate Names ether driver arpcom define is ac gt lt H define is_if define ztime gt lt define ac_enaddr define ctrblk gt define is_addr ZK 1274U AI 3 2 Enabling Support for Enhanced Hardware Management Enhanced hardware management EHM is a feature of Tru64 UNIX Version 5 0 that allows a system administrator to view and possibly modify various attributes of the hardware on either a local or a remote system To support this facility device drivers and bus drivers must provide their specific predefined attributes toa centralized management entity Examples of these attributes for network drivers include the type of LAN device its hardware address the type of media it is attached to and how fast it can operate The LAN subsystem supplies access routines for defining and exporting these attributes To use these routines a network driver must declare anet_hw_mgmt data structure as shown by the following code struct net_hw_mgmt ebm 4 Declares anet_ hw mgmt data structure and calls it ehm 3 3 Defining Media State Information The media state information contained in a network driver s softc data structure consists of informat
127. n and because network device drivers are associated with some device they also must have a device register header file Network Device Driver Environment 1 1 Figure 1 1 Sections of a Network Device Driver Network Device Driver r Include Files Section r Declarations Section r Configure Section r Initialization Section Autoconfiguration Support Section Start Transmit Section loctl Section Interrupt Section Reset Section Watchdog Section ZK 0818U Al Unlike for block and character drivers you do not specify network driver entry points in the dsent data structure This means that a network driver has no exposure into the file system and therefore has no entry in the dev directory Thus network drivers do not have block and character driver specific interfaces such as open close read write and strategy 1 2 Network Device Driver Environment Instead of registering its entry points in a dsent data structure a network driver registers its entry points with the upper layers of the Tru64 UNIX operating system in an ifnet data structure For example a network driver registers entry points for queueing data for transmission and for starting data transmission In addition to storing the entry points for a network driver s associated interfaces the ifnet data structure stores parameter related information such as the transmission medium and statistics to track the
128. nce information in the if e1 driver s el _softc data structure consists of a variable that stores a value that the device keeps on board The following code shows its declaration This information is hardware specific so you can omit it from your network device driver s softc data structure unsigned long txfree 3 9 Defining Bus Specific Information The bus specific information in a network driver s softc data structure consists of information about the bus or buses on which the driver operates The if_el driver operates on the PCMCIA and ISA buses so that the information in this section reflects these buses The following code shows the bus specific declarations in the if e1 device driver s el_softc data structure The bus specific information that is described here may not apply to your network device driver However the declarations do give you an idea of some of the information that a network driver needs to keep when operating on the PCMCIA and ISA buses int irg 1 int iobase 2 int isa_tag 3 int cardout 4 int reprobe 5 int ispemcia 6 struct card_info cinfop L7 Contains the interrupt request IRQ to use Defining the softc Data Structure 3 7 2 Contains the I O base address 3 Contains a tag value that identifies 3Com 3C5x9 devices on an ISA bus 4 Contains a value that indicates whether the use
129. nd Release Notes contains instructions on how to install the Device Driver Kit Version 2 0 product including source code with examples and user manuals It also describes changes to the product and documentation since the Device Driver Kit Release 1 0 xiv About This Manual e Writing Device Drivers contains information that you need to develop device drivers on the Compaq Tru64 UNIX operating system e Writing Kerna Modules describes topics for all kernel modules such as kernel threads and writing kernel modules in a symmetric multiprocessing SMP environment e Writing PCI Bus Device Drivers describes PCI bus specific topics including PCI bus architecture and data structures that PCI bus device drivers use e Writing VMEbus Device Drivers describes VME bus specific topics including VMEbus architecture and routines that VMEbus device drivers use e The Guideto Preparing Product Kits describes how to create kernel device driver product kits and layered product kits e Kernel Debugging describes how to use the dbx kdbx and kdebug debuggers to find problems in kernel code It also describes how to write a kdbx utility extension and how to create and analyze a crash dump file e Programming Support Tools describes several commands and utilities in the Tru64 UNIX system including facilities for text manipulation macro and program generation and source file management e The Programmer s Guide describes the programming environme
130. ne discards all pending transmits after the user has removed the card from the system static void el_start_locked struct el _softc sc struct ifnet ifp struct mbuf m ms mp mnj int len i j val unsigned char dat struct ether header eh 1 if sc gt cardout 2 Implementing the Start Section 9 3 IF_DEQUEUE amp ifp gt if_snd m 3 while m 4 m_freem m IF_DEQUEUE amp ifp gt if_snd m return 1 Declares a pointer toan ether header data structure called eh The ether header data structure contains information that is associated with a 10 Mb s and 100 Mb s Ethernet header 2 If the cardout member of the el_softc data structure for this device is set to 1 true the user removed the PCMCIA card from the slot 3 Callsthe IF DEQUEUE macro to remove an entry from the output queue The output queue is referenced through the if snd member of the ifnet data structure for this device The memory buffer information that IF_DEQUEUE manipulates is specified in the instance of the mbuf data structure called m 4 As long as a transmit request was dequeued from the output queue calls m_freem tofreethe request and IF_DEQUEUE to dequeue the next transmit request 9 2 2 Removing Packets from the Pending Queue and Preparing the 9 4 Transmit Buffer The following code shows how the el_start_locked routine
131. ng fails the request Determines whether autosensing has changed If autosensing is now disabled selects the last known media Determines whether the explicit media type selection has changed N o If the requested media value is out of range or not supported by the EtherLink III family fails the ioct1 request immediately The EtherLink III family supports the usual 802 3 media The if el driver does not check the card s capability in the registers because it is not useful to do so The registers always indicate they have all media regardless of what they really have 12 12 Implementing the ioctl Section If the user sets media that the card does not have the interface may not work 9 Selects the new mode 10 Resets the device to pick up the new mode if the interface was running 41 The default case returns an error that indicates that the caller has issued an invalid ioct1 command 12 17 Releasing the Simple Lock and Resetting the IPL The following code shows how the el_ioct1 routine releases the simple lock and resets the IPL if lock_on 4 simple unlock amp sc gt el_softc_lock splx s return status 2 If the simple lock is still held calls the simple unlock routine N Returns the status of the ioct1 request Implementing the ioctl Section 12 13 13 Implementing
132. ng the el shutdown Routine eeee eee 5 17 5 3 Implementing the el_autosense_thread Routine 5 17 5 3 1 Setting Up the el_autosense thread Routine 5 19 5 3 2 Blocking Until Awakened ccce eee eee ee eee eee 5 19 5 3 3 Testing for the Termination Flag ccceeeeee eee ees 5 20 5 3 4 Starting Up Statistics cece eee teen eed 5 20 iv Contents 5 3 5 Entering the Packet Transmit Loop 0 cceeeee ees 5 20 5 3 6 Saving Counters Prior to the Transmit Operation 5 21 5 3 7 Allocating Memory for a Test Packet 0c cease eee 5 21 5 3 8 Using the Default from the ROM cceeeee eee eee 5 21 5 3 9 Setting the Media in the Hardware eeeeees 5 22 5 3 10 Building the Test Packet cceeeeeee eee teat eee eee 5 22 5 3 11 Transmitting the Test Packet cceeeeeeee eee eee eee 5 22 5 3 12 Setting a Timer for the Current Kernel Thread 5 23 5 3 13 Testing for Loss of Carrier ccccece cece eee eeee teat eee 5 23 5 3 14 Determining Whether Packets Were Transmitted SUGGESSPUIIY ois ee isc ee Saadeh el Sad Acre e 2 Shel 5 24 5 3 15 Printing Debug Information cece eset e eee eee eee 5 24 5 3 16 Setting Up New Media ccc cccee eee ee teeter eae eee 5 24 5 3 17 Establishing the Media c cece eecee eee eae eee eens 5 25 6 Implementing the Autoc
133. nhanced hardware management Enhanced hardware management EHM allows you to modify hardware attributes such as the type of LAN device on either a local or a remote system See Section 3 2 for moreinformation about how a network device driver uses routines to define and export hardware attributes e Theunattach routine Theunattach routine stops the network device and frees resources prior to unloading the device driver or powering off the bus to which the device is attached See Chapter 7 for more information Organization This manual is organized as follows Chapter 1 Describes the sections that make up a network driver and compares them to the sections that are associated with block and character drivers Chapter 2 Describes the device register offset definitions for the if _e1 device driver s associated LAN device the 3Com 3C5x9 series Ethernet adapter Chapter 3 Describes how to define a softc data structure usingthe if el device driver s el_softc structure as an example Chapter 4 Describes how to implement a configure interface using the if _el device driver s el_configure routine as an example Chapter 5 Describes how to implement a probe interface and associated routines using the if_el device driver s el_probe routine as an example Chapter 6 Describes how toimplement an attach interface using theif _e1 device driver s el_attach routine as an example Chapter 7 Describes how to implemen
134. nitions 2 7 2 5 Window 1 Operational Register Offset Definitions 2 9 2 6 Window 4 Diagnostic Register Offset Definitions 2 11 2 7 EEPROM Data Structure Definition c cece eee 2 13 3 Defining the softc Data Structure 3 1 Defining Common Information ccceeeee cnet eee eee eee 3 2 3 2 Enabling Support for Enhanced Hardware Management 3 4 3 3 Defining Media State Information c cece eee eee eee 3 4 3 4 Defining the Base Register sssssrsrrerrrrrrrrrrrrrrrrrer 3 6 3 5 Defining Multicast Table Information cc cece eee eee 3 6 Contents iii 3 6 Defining the Interrupt Handler ID cceeeeeee eee eee 3 6 3 7 Defining CSR Pointer Information cceeeeeeee eee eee 3 6 3 8 Defining FIFO Maintenance Information eeee 3 7 3 9 Defining Bus Specific Information eece cece eee eee 3 7 3 10 Defining the Broadcast Flag c cece eeeeee eee eee teat ees 3 8 3 11 Defining the Debug Flag c cece cece eee eee teeta tees 3 8 3 12 Defining Interrupt and Timeout Statistics c e 3 8 3 13 Defining Autosense Kernel Thread Context Information 3 9 3 14 Defining the Polling Context Flag ccc eeeee ee ee eee eee 3 9 3 15 Defining a Copy of the w3_eeprom Data Structure 3 10 3 16 Dedaring the Simple Lock Data Structure
135. nized bus type n unit return 0 break Determines which bus the if _e1 driver operates on by examining the constant that the bus configuration code has stored in the bus_type member The el _probe routine references this value through the controller data structure pointer s bus_hd member This pointer is the data structure that is associated with this 3Com 3C5x9 device Performs tasks related to the PCMCIA bus if bus_type evaluates to the constant BUS_PCMCIA Adds the I O handle to the base address of the card and stores it in the reg variable The reg variable becomes an argument in subsequent calls to the read and write macros Determines whether the card is a multifunction card or a single function card Calls the READ_BUS_D16 macro to read a word 16 bits from a device register that is located in the bus I O address space This read operation verifies that the EtherLink III card is attached If the data that READ _BUS_D16 returns is not equal to 0x6d50 calls the WRITE_BUS_D16 and DELAY macros The WRITE_BUS_D16 macro writes a word 16 bits to a device register that is located in the bus I O address space This specific write operation resets the card The DELAY macro spins waiting the specified number of microseconds before continuing execution Implementing the Autoconfiguration Support Section probe 5 5 6 Calls the READ BUS D16 macro a second time to determine whether the EtherLink III is attached If
136. nly queried You can specify a value in the sysconfigtab file fragment which is appended to the etc sysconfigtab database The cfgmgr framework obtains this value from the etc sysconfigtab database and stores it in the el_polling variable Describes the Polls Per Second attribute which is specific to this device driver It indicates the polls per second for interrupt processing Similar to the Polling attribute you can only specify a value for this attribute at configuration time The cfgmgr framework obtains this value from the etc sysconfigtab database and stores it in the el_pollint variable Ends the array by specifying the null string 4 2 Setting Up the el_configure Routine The following code shows how toset up the el_configure routine int el_configure cfg_op t op 4 return lan_configure op amp el_data L6 cfg_ attr _t indata 2 size_t indatalen 3 cfg_attr_t outdata 4 size_t outdatalen 5 Declares an argument called op to contain a constant that describes the configuration operation to be performed on the driver This argument evaluates to one of the following valid constants CFG_OP_CONFIGURE CFG _OP_UNCONFIGURE CFG _OP_ QUERY Or CFG_OP_ RECONFIGURE Declares a pointer toa cfg _attr_t data structure called indata which consists of input tothe el_configure routine The cfgmgr framework fills in th
137. nt of the Tru64 UNIX operating system with an emphasis on the C programming language e TheNetwork Programmer s Guide describes the Tru64 UNIX network programming environment and provides information on STREAMS programming e System Administration describes how to configure use and maintain the Tru64 UNIX operating system Reference Pages Tru64 UNIX reference pages also called manpages contain descriptions of the routines Section 9r data structures Section 9s loadable services routines Section 9u and global variables Section 9v that apply to device drivers Reader s Comments Compaq welcomes any comments and suggestions you have on this and other Tru64 UNIX manuals You can send your comments in the following ways e Fax 603 884 0120 Attn UBPG Publications ZK 03 3 Y 32 About This Manual xv e Internet electronic mail readers comment zk3 dec com A Reader s Comment form is located on your system in the following location usr doc readers_comment txt Please include the following information along with your comments e The full title of the book and the order number The order number is printed on the title page of this book and on its back cover e The section numbers and page numbers of the information on which you are commenting e Theversion of Tru64 UNIX that you are using e If known the type of processor that is running the Tru64 UNIX software The Tru64 UNIX Publications group cannot res
138. nterface adapter error routine as follows static void el_error struct el_softc sc struct ifnet ifp int i WRITE _CMD sc CMD _WINDOW4 i READ FDP sc 1 printf el d Adapter Failure 04X n ifp gt if_unit i el_reset_locked sc ifp ifp gt if_unit 2 Reads the FIFO diagnostic port register 2 Resets the adapter to clear the failure condition 13 12 Implementing the Interrupt Section 14 Network Device Driver Configuration Device driver configuration incorporates device drivers into the kernel to make them available to system administration and other utilities The operating system provides two methods for configuring drivers into the kernel static and dynamic Werecommend that you implement your driver products as a single binary module so that customers can statically or dynamically configure them into the kernel The driver s configure interface handles all configuration operations either at startup for static configuration or at run time for dynamic configuration To support configuration you must providea sysconfigtab file fragment which contains device special file and bus specific information The information in the sysconfigtab file fragment is added to the system s etc sysconfigtab database when the driver is installed The startup procedure and the sysconfig utility use the information that the etc sysconfigtab database provides to locate t
139. o the array of pointers to controller data structures el_info ctlr_unattach which specifies the driver s controller unattach interface el _unattach 1 2 4 Defining Driver Specific Macros To help you write more portable device drivers Tru64 UNIX provides the following kernel routines which allow you to read from and write toa control status register CSR address without directly accessing its device registers These macros call the read_io port or write _io port generic routines Network Device Driver Environment 1 7 READ BUS D8 READ BUS D16 READ BUS _D32 READ BUS D64 WRITE BUS _D8 WRITE BUS D16 WRITE BUS _D32 WRITE BUS D64 Reads a byte 8 bits from a device register Reads a word 16 bits from a device register Reads a longword 32 bits from a device register Reads a quadword 64 bits from a device register Writes a byte 8 bits to a device register Writes a word 16 bits to a device register Writes a longword 32 bits to a device register Writes a quadword 64 bits to a device register The following code shows how the if _e1 driver uses the READ BUS D16 READ BUS D32 WRITE BUS _D16 and WRITE BUS D32 kernel routines to construct driver specific macros to perform read and write operations on the 3Com 3C5x9 device define define define define define define define define READ CCR sc WRITE _CCR sc READ ACR sc WRITE _ACR sc WRITE _RCR sc WRITE_ECR sc READ_
140. obed which indicates that the device is operating on a PCMCIA bus and that the user has put the card back into the slot In this case the driver does not need to redo much of the initial probe work and will skip tothe code shown in Section 5 1 10 If this is a multifunction card reads the EEPROM data and saves it in sc gt eeprom If this is a multifunction PC card the EEPROM data is located in the card information data structure If this is not a multifunction PC card the EEPROM data is read directly from the card and saved in the el_softc data structure Saves the 48 bit physical address of the device into the is addr member of the e1_softc data structure for this 3Com 3C5x9 device Sets the media mode to the constant LAN MODE _AUTOSENSE This constant indicates that the driver hardware determines the media automatically Sets the media state tothe constant LAN MEDIA STATE SENSING This constant indicates that the media is currently in the autosensing state Sets the currently set media to the constant LAN MEDIA UTP This constant indicates that the mode for the media is unshielded twisted pair cable Implementing the Autoconfiguration Support Section probe 5 11 10 11 12 13 14 Calls the kernel_thread_w_arg routine to create and start a kernel thread with timeshare scheduling A kernel thread that is created with timeshare scheduling means that
141. oc el unit sizeof struct ether driver 1 CLEAR _LAN COUNTERS sc gt is_ed 2 Calls a routine that returns an ether driver data structure and initializes the ifnet portion of it Implementing the Autoconfiguration Support Section probe 5 7 Initializes all Ethernet statistics counters in the ether driver data structure to 0 zero N 5 1 6 Initializing the Enhanced Hardware Management Data Structure The following code shows how the el _probe routine initializes the data structure for enhanced hardware management EH M support lan_ehm_init amp sc gt ehm NET_EHM VERSION ID 1 1 Initializes the net _hw_mgmt data structure This data structure contains the current and default attribute values for this device as well as other information that EHM requires The lan_ehm_init routine allocates all necessary storage and performs basic initialization of the EHM data structure Makesurethat your driver makes this call as well 5 1 7 Computing the CSR Addresses The following code shows how the el_probe routine determines the addresses of the if e1 device s control and status CSR registers sc gt regE reg 0xe 1 sc gt regC reg Oxc L2 sc gt regA reg 0xa sc gt reg8 reg 0x8 sc gt reg6 reg 0x6 sc gt reg4 reg 0x4 sc gt reg2 reg 0x2 sc gt regO reg 0x0 sc gt data reg 0x0 s
142. of this array Declares a variable called el _isa_tag and initializes it to the value 0 zero The if el driver s el_isa_ activate interface uses this variable Declares a variable called e1 isa reset and initializes it to the value 0 zero The if_el driver s el probe interface uses this variable Uses the decl_ simple lock info routine to declare a simple lock data structure called el_lock_info 1 6 Network Device Driver Environment 1 2 3 Declaring and Initializing the driver Data Structure The following code shows how the if _e1 device driver declares and initializes the driver data structure with the names of its entry points static struct driver eldriver 1 erl probe 0 el attach 0 ooo 0 el el_info 0 0 0 0 0 e l_unattach 1 Declares and initializes the driver data structure called eldriver Because a network device driver does not have exposure to the file system it does not provide open close read write and strategy interfaces The members of the driver data structure that specify these entry points are initialized to 0 zero Theif_el driver initializes the following members to nonzero values probe which specifies the driver s probe interface el probe cattach which specifies the driver s controller attach interface el_ attach ctlr_name which specifies the controller name e1 ctlr_list which specifies a pointer t
143. oftc and controller data structures are associated with a specific 3Com 3C5x9 device Thedriver s el_probe interface initializes these arrays if the probe operation is successful The arrays of el _softc and controller data structures need to be static for the if el device driver Be aware that static arrays fix the maximum number of devices that the user can configure on the system define el_MAXDEV 7 1 static struct el _softc el_softc el_MAXDEV 0 L2 static struct controller el_info el_MAXDEV 0 3 static int el_isa_tag 0 4 static int el isa reset 0 5 decl_simple_ lock _info static el_lock_info 6 1 Defines a constant called e1_MAXDEv which allocates data structures that the if _e1 device driver needs A maximum of seven instances of the 3C5x9 controller can be on the system This means that el MAXDEV is the maximum number of controllers that the if e1 driver can support This is a small number of instances of the driver and the data structures themselves are not large soit is acceptable to allocate for the maximum configuration Declares an array of pointers toel_softc data structures and calls it el_softc Theel_ MAXDEV constant specifies the size of this array Declares an array of pointers to controller data structures and calls itel_ info The el_MAXDEv constant specifies the size
144. og el watch 2 ifp gt if_start int el_start 3 mb ifp gt if_output ether output 4 mb ifp gt if_flags IFF_BROADCAST IFF MULTICAST IFF_NOTRAILERS IFF_SIMPLEX 5 ifp gt if_timer 0 6 ifp gt if_sysid_type 0 7 ifp gt if_version 3Com EtherLink III L8 1 Sets theif ioctl member of the ifnet data structure for this device toel_ioct1 whichistheif el devicedriver s ioct1 interface 2 Sets theif watchdog member of the ifnet data structure for this device to el_watch whichis the if _e1 device driver s watchdog interface 6 6 Implementing the Autoconfiguration Support Section attach Sets the if start member of the ifnet data structure for this device toel_start whichis theif el device driver s start transmit for output interface Sets the if output member of the ifnet data structure for this device toether output whichis the if el device driver s output interface Tru64 UNIX provides this kernel routine All network device drivers including Token Ring and FDDI drivers must set if output toether output rather than implementing a driver specific output interface An mb memory barrier preceeds the setting of the if output member Members of the ifnet structure must be initialized in the order shown The mb
145. oint for the start interfacein the ifnet data structure However before this interface can be called the network adapter must be enabled for data packet transmission and reception You enable the network adapter by invoking the SIOCSIFADDR ioctl command 1 10 Network Device Driver Environment 1 7 Watchdog Section for a Network Driver The watchdog section for a network device driver contains a watchdog interface which attempts to restart the adapter The watchdog interface is optional in a network device driver If the network device driver implements it watchdog is called by a kernel thread if the driver s interrupt handler has not shut down the countdown timer within a certain number of seconds of queueing a data packet for transmission from the upper layer This indicates that the adapter is no longer on line 1 8 Reset Section for a Network Driver The reset section for a network device driver contains a reset interface The reset interface resets the LAN adapter This interface is called to restart the device following a network failure This interface resets all of the counters and local variables It can also free up and reallocate all of the buffers that the network driver uses 1 9 ioctl Section for a Network Driver The ioctl section for network device drivers performs miscellaneous tasks that have nothing to do with data packet transmission and reception Typically these tasks relate to turning specific features of the hardwa
146. omatically determine the network interface or whether the user specified the type of media The 1m_media member specifies the current media This member changes each time that the driver uses a different medium to try to transmit a packet The if_e1 device driver can set this member to any of the following values LAN _MEDIA_UTP The media is unshielded twisted pair cable LAN MEDIA BNC The media is thin wire LAN_MEDIA_AUI The media is the attachment unit interface AUI The 1m_media_state member specifies the current state of the autosensing procedure as follows LAN MEDIA STATE SENSING The driver is trying to determine the media mode LAN _MEDIA_STATE DETERMINED The media state has been determined Theel_ autosense thread routine is implemented as a kernel thread It performs the following tasks Blocks until awakened Section 5 3 2 Tests for the termination flag Section 5 3 3 Starts up statistics Section 5 3 4 Enters the packet transmit loop Section 5 3 5 Saves counters prior to the transmit operation Section 5 3 6 Allocates memory for a test packet Section 5 3 7 Uses the default from the ROM Section 5 3 8 Sets the media setting in the hardware Section 5 3 9 Builds a test packet to transmit Section 5 3 10 Transmits the test packet Section 5 3 11 Sets a timer for the current kernel thread Section 5 3 12 Tests for loss of carrier Section 5 3 13 5 18 Implementing t
147. onfiguration Support Section attach 6 1 Setting Up the el_attach Routine c cece eee eee eee 6 1 6 2 Initializing the Media Address and Media Header Lengths 6 2 6 3 Setting Up the Media ccc ccc eee eee eee eee eee eae 6 3 6 4 Initializing Simple Lock Information c eceeeee eee eee 6 5 6 5 Printing a Success Message 6 cece cece eee teeta ee eee 6 6 6 6 Specifying the Network Driver Interfaces eeen 6 6 6 7 Setting the Baud Rate eee ec ee eee ence eee teeta eens 6 8 6 8 Attaching to the Packet Filter and the Network Layer 6 8 6 9 Setting Network Attributes and Registering the Adapter 6 9 6 10 Handling theReinsert Operation cece cece ee eee 6 9 6 11 EnablingtheInterrupt Handler c cece cece eee eee 6 10 6 12 Starting the Polling Process c ccc eeeee eee eee ee eee eee 6 10 7 Implementing the unattach Routine 7 1 Setting Up the el_unattach Routine cece cence eee 7 1 7 2 Verifying That the Interface Has Shut Down 655 7 2 7 3 Obtaining the Simple Lock and Shutting Down the Device 7 2 7 4 Disabling the Interrupt Handler ceceeeeee eee e eee eee 7 3 7 5 Terminating the Autosense Kernel Thread iccse 7 3 7 6 Unregistering the PCMCIA Event Callback Routine 7 4 7 7 Stopping the Polling Process cceeeee tees ee ee teeta 7 4 7 8 Unregistering the Shutdown Routine
148. onstituting an additional warranty Contents About This Manual 1 Network Device Driver Environment 1 1 Include Files Section for a Network Driver l 1 3 1 2 Declarations Section for a Network Driver ceeeeeee 1 4 1 2 1 External and Forward Declarations 0 eeee eee 1 5 1 2 2 Declaring softc and controller Data Structure Arrays 1 6 1 2 3 Declaring and Initializing the driver Data Structure 1 7 1 2 4 Defining Driver Specific Macros 0 cece cece eee eee eee 1 7 1 3 Configure Section for a Network Driver eeeeeee eee 1 10 1 4 Autoconfiguration Support Section for a Network Driver 1 10 1 5 Initialization Section for a Network Driver s es 1 10 1 6 Start Section for a Network Driver 0cceeceee eee eee e eee 1 10 1 7 Watchdog Section for a Network Driver cccceeeseeeeeeeees 1 11 1 8 Reset Section for a Network Driver eeeeeeee eee 1 11 1 9 ioctl Section for a Network Driver ccceeeee cnet eee tees 1 11 1 10 Interrupt Section for a Network Driver ccceeeee eee eee 1 11 1 11 Output Section for a Network Driver c cece eee 1 11 2 Defining Device Register Offsets 2 1 Interrupt and Status Register Offset Definitions 2 1 2 2 Command Port Register Offset Definitions cceneees 2 2 2 3 Window 0 Configuration Register Offset Definitions 2 4 2 4 Window 3 Configuration Register Offset Defi
149. or this device The controller number which is stored in the unit variable is used as an index into the array of el_softc data structures to determine which el_softc data structure is associated with this 3Com 3C5x9 device e Sets the cardout member of the el_softc data structure to the value 0 zero to indicate that the PCMCIA card is not currently removed from its slot e Sets the reprobe member of the el_softc data structure to the value 1 toindicate that the PCMCIA card was reinserted intoits slot 2 If this is an ISA device or if the user did not remove and replace the card calls the MALLOC macro to allocate memory for the el_softc data structure 3 If MALLOc could not allocate the memory calls the printf routineto display an appropriate message on the console terminal The printf routine also displays the controller number for the device 4 Returns the value 0 zero to the bus configuration code to indicate that the probe operation failed 5 1 5 Allocating the ether_driver Data Structure The following code shows how the el_probe routine calls if alloc to allocate the ether_driver data structure for this device if alloc returns an ether driver data structure which contains the ifnet data structure and initializes the if name if unit and if_index fields Make sure that your driver allocates its ether driver data structurein the same way sc gt is_ed if _all
150. ormation Interrupt Handler ID Context Information ZK 1273U Al A single asterisk denotes information that all network device drivers provide in the associated softc data structure and a double asterisk denotes information that is specific to the hardware or bus 3 1 Defining Common Information The common information in a local area network driver s softe data structure is contained inthe ether driver data structure which consists of information such as counter blocks media state media values and so forth The following code shows the declaration and definition of the common information in the if _e1 device driver s el _softc data structure Make sure that the common part of your softc data structure has the same declaration and definitions struct el_softc struct ether driver is_ed 1 3 2 Defining the softc Data Structure define is_ac is_ed gt ess_ac 2 define ztime is_ed gt ess_ztime 3 define ctrblk is _ed gt ess_ctrblk 4 define is if is _ac ac_if 5 define is_addr is_ac ac_enaddr 6 1 Declares an instance of the ether driver data structure and calls itis ed All network drivers must have an ether driver data structure By convention a pointer to this data structure is the first element in the softc data structure Maps the ess ac member of the ether d
151. outine to process the received Ethernet packet The packet is in the mbuf chain without the ether header data structure which is provided separately 13 2 5 Discarding a Packet The following code shows how the el_rint routine discards a packet Some receive interrupt handlers perform a copy of a few bytes of the packet to determine if the packet is actually destined for the device Thus this task is an optional optimization scrap 1 WRITE _CMD sc CMD _RXDTP status READ RXS sc Implementing the Interrupt Section 13 9 if sc gt debug amp amp count lt 0 printf el d Receive in INFINITE loop 04X n ifp gt if_unit status Calls the WRITE _CMD macro to write data to the command port register The data to be written is the receive discard top packet command CMD_RXDTP 13 3 Implementing the el_tint Routine Theif_el devicedriver s el _tint routine is the transmit interrupt completion routine It performs the following tasks e Counts the transmit interrupt Section 13 3 1 e Reads the transmit status and counts all significant events Section 13 3 2 e Manages excessive data collisions Section 13 3 3 e Writes to the status register to obtain the next value Section 13 3 4 e Queues other transmits Section 13 3 5 13 3 1 Counting the Transmit Interrupt The following code shows how the el_tint routine counts the transmit interrupt define TXLOOP 16 10
152. pond to system problems or technical support inquiries Please address technical questions to your local system vendor or to the appropriate Compaq technical support office Information provided with the software media explains how to send problem reports to Compaq Conventions This manual uses the following conventions A vertical ellipsis indicates that a portion of an example that would normally be present is not shown In syntax definitions a horizontal ellipsis indicates that the preceding item can be repeated one or more times file Italic Slanted type indicates variable values placeholders and function parameter names buf In function definitions and syntax definitions used in driver configuration this typeface indicates names that you must type exactly as shown In formal parameter declarations in function definitions and in structure declarations brackets indicate arrays Brackets also specify ranges for device minor numbers and device special files in file fragments However for the syntax definitions xvi About This Manual that are used in driver configuration these brackets indicate items that are optional Vertical bars separating items that appear in the syntax definitions used in driver configuration indicate that you choose one item from among those listed About This Manual xvii 1 Network Device Driver Environment A network device is responsible for both transmitting and receiving frames
153. r 9 7 output process marking as active 9 7 output section 1 11 P PCI_Option entry sysconfigtab file fragment 14 1 PCMCIA bus discarding all transmits 9 3 initializing bus specific data structure 5 8 probe 5 4 first time 5 10 reload operation in el_attach 6 9 in el_init 8 2 PCMCIA card determining if the user has removed from the slot in el_ioctl 12 3 physical address reading current 12 5 polling context flag 3 9 polling process starting 6 10 probe interface 5 1 autoconfiguration support 5 1 R packet copying the first part 13 7 determining successful transmit 5 24 discarding 13 9 pulling from the FIFO information 13 6 transmitting 9 4 transmitting pending 8 11 packet filter attaching 6 8 packet transmit loop entering 5 20 read driver specific macros 1 8 receive interrupt counting 13 5 data transfer 13 8 receive operation processing completed 13 3 receiver resetting 8 4 8 7 register offset 2 1 registering adapters 6 9 reload operation in el_attach 6 9 in el_init in e_init 8 2 reset section 1 11 implementing 11 1 Index 5 ROM using the default from 5 21 RX status reading 13 5 S section autoconfiguration support 1 10 5 1 6 1 configure 1 10 declarations 1 4 include files 1 3 initialization 1 10 8 1 interrupt 1 11 13 1 ioctl 1 11 12 1 output 1 11 reset 1 11 11 1 start 1 10 9 1 watchdog 1 11 10 1 setting network
154. r has ejected the PCMCIA card 5 Contains a value that indicates whether the user has reloaded the PCMCIA card 6 Contains a value that indicates whether the card is a PCMCIA card 7 Declares a pointer tothe card_info data structure and calls it cinfop The card_info data structure contains information that is necessary to communicate with the kernel PCMCIA subsystem 3 10 Defining the Broadcast Flag The broadcast flag in the if e1 driver s el_softc data structure indicates whether the device should receive broadcast traffic This flag is specific to the if_e1 driver and therefore is optional in most network device drivers The following code shows the declaration of the broadcast flag in the if el device driver s el_softc data structure int is_broadcast 1 1 Contains a boolean value If true the broadcast address flag is set 3 11 Defining the Debug Flag The debug flag in a network driver s softc data structure indicates whether debug mode is on The following code shows the declaration of the debug flag inthe if el devicedriver s el _softc data structure The debug flag is optional int debug 1 Contains the status of the debug flag If the if flags member of the ifnet data structure pointer is set to IFF_DEBUG debug is on Otherwise debug is off 3 12 Defining Interrupt and Timeout Statistics The interrupt and timeout
155. r totheel intr routine theif el devicedriver s interrupt handler e Theunit variable which contains the controller number for this device This argument is passed tothe el_intr routine e Theel_pollint variable which specifies the amount of time to delay before calling the el _intr routine Implementing the Interrupt Section 13 1 3 Reading the Interrupt Status 13 1 4 The following code shows how the el_intr routine uses the READ STS macro to read the interrupt status from the I O status register status READ STS sc Processing Completed Receive and Transmit Operations The following code shows how the el_intr routine processes the receive and transmit rings if status amp S_RC S TC S AF 0 sc gt cardout 1 simple unlock amp sc gt el_softc_lock splx s while status amp S RC S TC S AF amp amp el_card_out sc L2 return INTR_NOT_SERVICED if status amp S RC el_rint sc ifp if status amp S TC el _tint sc ifp if status amp S AF el_error sc ifp status READ STS sc Examines the status that the READ_STS macro returns If the status variable does not have the receive complete S_Rc bit the transmit complete S_Tc bit or the adapter failure S_AF bit set or if the PCMCIA card is out of the slot Calls the simple unlock routine to release the simple lock for the resource that is a
156. re on or off The ioctl section contains an ioct1 interface You define this entry point in the ifnet data structure 1 10 Interrupt Section for a Network Driver The interrupt section for a network device driver contains an interrupt handler The interrupt handler processes network device interrupts You define the entry point for the interrupt handler by calling the handler interfaces The interrupt handler is called each time that the network interface receives an interrupt After identifying which type of interrupt was received transmit or receive the interrupt handler calls the appropriate routine to process the interrupt 1 11 Output Section for a Network Driver The output section for a network device driver formats a data packet for transmission on the network The ether_output routine formats data packets for Tru64 UNIX network drivers Despite its name ether output handles the frame formats for Ethernet token ring and FDDI After it has properly formatted the data packet ether output enqueues the packet on the driver s send queue and calls the driver s start Network Device Driver Environment 1 11 interface to transmit the data All network drivers must set the output member of the ifnet data structure to ether output 1 12 Network Device Driver Environment 2 Defining Device Register Offsets The device register header file defines the device register offsets for the device The if _elreg h fil
157. removes packets from the pending queue and prepares the transmit buffer while 1 2 IF_DEQUEUE amp ifp gt if_snd m 2 if m amp amp m gt m_pkthdr len 8 lt sc gt txfree 3 ms m 4 while ms amp amp ms gt m_len 0 5 ms ms gt m next 6 if ms NULL 7 m_freem m continue Implementing the Start Section mp ms 8 mn mp gt m_next len mp gt m_len while mn NULL if mn gt m_len mp gt m_next 9 1 11 0 mn gt m_next tou tt ejo mn gt m_next NULL m_free mn else 12 len mn gt m_len mp mn mn mp gt m_next While true removes packets from the pending queue and has the device transmit the packets Calls the IF_DEQUEUE macro to remove an entry from the output queue The output queue is referenced through the if snd member of the ifnet data structure for this device The memory buffer information is the instance of the mbuf data structure called m Checks that the total packet length is less than the number of bytes left in the transmit first in first out FIFO Eliminates any zero length segments The ms mbuf pointer will point to the first buffer segment with data Skips over any leading zero l
158. rforms the following tasks e Sets theIPL and obtains the simple lock Section 10 1 e Increments the transmit timeout counter and calls the el_ reset _locked routine to reset the unit Section 10 2 e Releases the simple lock and resets the IPL Section 10 3 10 1 Setting the IPL and Obtaining the Simple Lock The following code shows how to set up the el_watch routine and shows how el_watch setstheIPL and obtains the simple lock static int el_watch int unit register struct el softo sc el _softc unit register struct ifnet ifp amp sc gt is_ if int s s splimp L121 simple _ lock amp sc gt el_softc_lock 2 Calls the splimp routine to mask all LAN hardware interrupts On successful completion splimp stores an integer valuein thes variable This integer value represents the CPU priority level that existed prior tothe call to splimp Implementing a Watchdog Section 10 1 2 Callsthe simple _lock routine to assert a lock with exclusive access for the resource that is associated with the el_softc_lock simple lock data structure pointer This means that no other kernel thread can gain access to the locked resource until you call simple unlock to release it Because simple locks are spin locks simple _lock does not return until the lock has been obtained 10 2 Incrementing the Transmit Timeout Counter and Resetting the Unit The fo
159. river data structure to the alternate name is_ac Theess_ac member is referred to as the Ethernet common part and is actually an instance of the arpcom data structure Figure 3 2 shows the is_ ac alternate name and associated mapping Maps the ess_ztime member of the ether driver data structure to the alternate name ztime The ess_ztime member stores the time counters that were last zeroed Figure 3 2 shows the zt ime alternate name and associated mapping Maps the ess_ctrblk member of the ether driver data structure tothe alternate name ctrblk The ess_ctrb1k member is referred to as the counter block and is actually an instance of the estat data structure Figure 3 2 shows the ct rb1k alternate name and associated mapping You must define this line in your network device driver if you plan to use ADD _RECV_MPACKET ADD RECV_ PACKET ADD XMIT MPACKET and ADD_XMIT_PACKET for maintaining LAN device counters Each of these macros references the ct rb1k alternate name Maps the ac_if member of the arpcom data structure to the alternate nameis_ if Theac_if member is referred to as the network visible interface and is actually an instance of the ifnet data structure Figure 3 2 shows the is_ if alternate name and associated mapping Maps the ac_enaddr member of the arpcom data structure to the alternatenameis addr Thenameac_enaddr is actually an alternate name for ac_hwaddr which is the name of the actual member of the arpco
160. rk management software This unique number is referred to as the MOP system D device code Implementing the Autoconfiguration Support Section attach 6 7 Sets the if version member of the ifnet data structure for this device to the string 3Com EtherLink III 6 7 Setting the Baud Rate The following code shows how the el_attach routine sets the baud rate ifp gt if_baudrate ETHER _BANDWIDTH_10MB 1 Sets the if baudrate member of the ifnet data structure for this device to the constant ETHER_ BANDWIDTH _10MB The if baudrate member specifies the line speed You can use the following media specific constants ETHER BANDWIDTH_10MB Ethernet line speed is 10 megabits per second The if_ether h file defines the ETHER_BAND WIDTH _10MB constant ETHER _BANDWIDTH_100MB Fast Ethernet line speed is 100 megabits per second The if_ether h file defines the ETHER_BAND WIDTH_100MB constant FDDI_BANDWIDTH_100MB FDDI line speed is 100 megabits per second The if _fddi h file defines the FDDI_BANDWIDTH_100MB constant TRN_BANDWIDTH_4MB Token Ring line speed is 4 megabits per second The if _trn h file defines the TRN_BANDWIDTH_4MB constant TRN_BANDWIDTH_16MB Token Ring line speed is 16 megabits per second The if_trn h file defines the TRN_BANDWIDTH_16MB constant 6 8 Attaching to the Packet Filter and the Network Layer The following code shows how th
161. rocessing completed operations 13 3 queuing 13 12 reading status 13 10 saving counters 5 21 transmitter resetting 8 4 8 7 TX and RX enabling 8 9 U unattach interface 7 1 unit resetting 10 2 V VBA_Option entry sysconfigtab file fragment 14 1 W w3_eeprom data structure 2 13 in el_softc data structure 3 10 watchdog interface 10 1 indicating when to start 9 8 watchdog section 1 11 implementing 10 1 window 0 configuration register offset definitions 2 5 window 1 operational register offset definitions 2 9 window 3 configuration register offset definitions 2 8 window 4 diagnostic register offset definitions 2 11 write driver specific macros 1 8 Index 7
162. ros Section 1 2 4 The following sections discuss each of these categories of declarations using the if el device driver as an example The declarations section also contains the definition of the softc data structure and declarations for configure related variables and data structures Chapter 3 discusses the definition of a network driver s softc data structure Section 4 1 discusses the declarations that are related to configuration 1 2 1 External and Forward Declarations The following code shows the external and forward declarations for the if_el device driver int el_configure cfg_op t cfg_attr_t size t efg attr t size t 1 static int static int static int static int static int static void static void static int static void static void static int static int static void static void static void static void static void _probe io _ handle t struct controller 2 _attach struct controller _unattach struct bus struct controller _init_locked struct el softe struct ifnet int _init int _start_locked struct el softe struct ifnet _start struct ifnet _watch int _reset_locked struct el_softc struct ifnet int _reset int _ioctl struct ifnet u int cadar t _intr int Yint struct l softo struct ifnet tint struct el softe struct ifnet _error struct l softo struct ifnet _shutdown struct el_soft
163. rupt Section eh mtod m eh ether_type ADD_RECV_PACKET ifp if ADD_RECV_MPACKET ifp struct ether header j ntohs unsigned short eh et m gt m_data sizeof struct ether header sc m gt m_pkthdr len eh ether dhost 0 amp 0x1 2 her type 4 5 sc m gt m_pkthdr len i if READ RXS sc i amp Ox7 f if i amp 0x400 m_freem m goto scrap 0 ether input ifp amp eh m Calls the io_blockread routine to perform the data transfer from the FIFO buffer on the adapter to the mbuf in host memory Makes a copy of the ether_header data structure for the ether_input routine Converts the 2 byte ether_type field from network byte order to host byte order and saves it in the ether_header data structure Adjusts the pointer to the received data to point past the MAC header skips past the destination address source address and ether_type fields Calls the ADD_RECV_PACKET macro to increment the receive packet block count If this packet was destined for a broadcast or multicast address calls the ADD _RECV_MPACKET macro to increment those statistics as well Calls the READ _RxS macro to read the receive status If the packet just received was not fully received scraps the packet Calls the ether input r
164. rupt mask and enable adapter failure S_AF transmit complete S_Tc and receive complete S_RC interrupts 2 If the deviceis polling calls the WRITE CMD macro to clear the interrupt mask and disable all interrupts 8 2 14 Setting the Operational Window The following code shows how the el_init locked routine sets the operational window This task is specific to the 3Com 3C5x9 device WRITE _CMD sc CMD _WINDOW1 1 sc gt txfree READ TXF sc Calls the WRITE _CMD macro to set the operational window register 8 2 15 Marking the Device as Running The following code shows how the el_init_locked routine marks the device as running All network device drivers perform this task 8 10 Implementing the Initialization Section ifp gt if_flags IFF_RUNNING 1 ifp gt if_flags amp IFF_OACTIVE 2 Sets the IFF_RUNNING flag to mark the device as running Clears the IFF_OACTIVE flag to indicate that there is no output outstanding N 8 2 16 Starting the Autosense Kernel Thread The following code shows how the el_init_locked routine starts the autosense kernel thread Only network device drivers that implement an autosense kernel thread perform this task if sc gt lm_media_mode LAN MODE AUTOSENSE 1 sc gt lm_media_state LAN MEDIA STATE SENSING thread_wakeup_one vm_offset_t amp sc gt autosense_ flag
165. s cases apply This indicates a size error 9 Allocates a buffer for the received data If the length of the received data is less than a small mbuf allocates a small mbuf Otherwise a 2K cluster mbuf is allocated This code is an optimization In most cases a driver does not know the size of a receive packet when the buffer resource is allocated 13 2 3 Examining the First Part of the Packet The following code shows how the el_rint routine examines the first part of the received packet if m NULL 4 m gt m_pkthdr len m gt m_len len sizeof struct ether_header 2 m gt m_pkthdr rcvif ifp m gt m_data 2 3 dat mtod m unsigned char 4 len len 3 amp 3 if ifp gt if_flags amp IFF_PROMISC IFF_ALLMULTI 0 5 io_blockread sc gt data vm_offset_t dat 2UL 4UL HANDLE LONGWORD 6 len 2 4 dat 2 4 if mtod m unsigned char amp 0x01 7 Implementing the Interrupt Section 13 7 9 10 if bcmp mtod m unsigned char etherbroadcastaddr 6 0 L8 int ix LAN FIND MULTI amp sc gt is_ multi mtod m unsigned char ix i 9 if i LAN_MULTI_FOUND 10 sc gt is_multi lan_mtable ix muse 0 m_freem m goto scr
166. s counters Section 12 10 SIOCRDZCTRS Yes Reads and zeros Section 12 10 counters SIOCSIFADDR Yes Brings up thedevice Section 12 11 Implementing the ioctl Section 12 1 Table 12 1 Network ioctl Commands cont ioctl Command Required Description For More Information SIOCSIFFLAGS Yes Ensures that the Section 12 12 interface is operating correctly according to the interface flags if flags SIOCSIPMTU Yes Sets the IP maximum Section 12 13 transmission unit MTU SIOCSMACS PEED Yes Sets the media speed Section 12 14 SIOCIFRESET No Resets the device Section 12 15 SIOCIFSETCHAR Yes Sets network device Section 12 16 characteristics such as full duplex or promiscuous mode 12 1 Setting Up the el_ioctl Routine 12 2 static int el _ ioctl struct ifnet ifp 1 The following code shows how to set up the el_ioct1 routine u_int cmd 2 caddr_t data 3 register struct el_softc sc el _softc ifp gt if_unit 4 register unit ifp gt if_unit 5 struct ifreq ifr struct ifreq data 6 struct ifdevea ifd struct ifdevea data 7 struct ctrreq ctr struct ctrreg data 8 struct ifchar ifc struct ifchar data 9 ESUCCESS 10 int s i j need_reset lock_on 1 status unsigned short ifmtu speed 11 u_char mclist_buf NET_S
167. s the EEPROM contents in the el_softc data structure 5 1 11 Registering the Interrupt Handler The following code shows how the e1_probe routine registers the interrupt handler The Writing Device Drivers manual provides detailed information on the data structures and routines that relate to the 5 14 Implementing the Autoconfiguration Support Section probe registration of interrupt handlers All network device drivers are required to register interrupt handlers el_intr_info configuration_st caddr_t ctlr 1 el_intr_info intr el_intr 2 el_intr_info param caddr_t unit 3 el_intr_info config type CONTROLLER_CONFIG TYPE 4 if ctlr gt bus_hd gt bus_type BUS _PCMCIA 5 el_intr_info config_type SHARED INTR_ CAPABLE el_ihandle ih bus ctlr gt bus_hd 6 el_ihandle ih bus info char amp el_intr info 7 sc gt hid handler_add amp el_ihandle 8 if sc gt hid ihandler_id_t NULL L9 printf el d interrrupt handler add failed n unit if sc gt ispcmcia pemcia_unregister_event_callback card_infop gt socket_vnum CARD_REMOVAL_ EVENT caddr_t el_card_remove if_dealloc sc gt is_ed lan_ehm_free amp sc gt ehm FREE sc M DEVBUF return 0 1 Sets the configuration_st member of the el_intr_info data structure to the pointer to the controller data
168. s the transmit and receive first in first out FIFO sizes bling TX and RX The following code shows how the el_init locked routine enables transmit TX and receive RX Make sure that you perform similar initialization tasks for the hardware device that your network driver controls Implementing the Initialization Section 8 9 WRITE _CMD sc CMD _RXENA 1 WRITE _CMD sc CMD _TXENA 2 1 Calls the WRITE CMD macro to write data to the command port register The data to be written is the receive RX enable command CMD_RXENA 2 Calls the WRITE CMD macro to write data to the command port register In this call the data to be written is the transmit TX enable command CMD_TXENA 8 2 13 Enabling Interrupts The following code shows how the el_init locked routine enables interrupts Make sure that you perform similar initialization tasks for the hardware device that your network driver controls LAN device drivers typically do not perform polling operations However this example shows how polling operations can be done on the 3Com 3C5x9 device if el_polling 2 WRITE _CMD sc CMD_ZINTMASK 0xfe WRITE CMD sc CMD SINTMASK S_AF S TC S RC else 2 WRITE _CMD sc CMD_ZINTMASK 0xfe WRITE _CMD sc CMD_SINTMASK 0 If the device is not polling the el polling flag is not set calls the WRITE _CMD macro to set the inter
169. ss of the current probe operation 4 Ifthe EEPROM address has changed converts the original EEPROM address to its canonical form 5 Compares the original EEPROM address to the hardware address that is currently in effect If they are different then a previously specified hardware address was used that was different from the address that was found in the EEPROM In this case the alternate address is still in effect and no further action needs to be taken 6 If the original EEPROM address is the same as the hardware address that is currently in effect uses the hardware address that was found in the EEPROM Because the EEPROM has changed because the old if _e1 adapter was removed and a new one inserted it will be necessary to broadcast the new EEPROM hardware address onto the network to inform the network that there has been a change This section of code converts the hardware address from the current EEPROM to canonical form in preparation for the broadcast message 7 Saves the new hardware address in the is_addr member of the el_softc data structure 8 Ifan IP address has been configured for this interface informs the network that there is a new hardware address for the IP address by sending out an ARP packet 9 Marks this new hardware address as the link address for this interface 10 Informs the packet filter of the new hardware address 11 Save
170. ssociated with el_softc_lock Calls the sp1x routine to reset the CPU priority to the level that the s variable specifies Returns the constant INTR_NOT_SERVICED tothe kernel interrupt dispatcher This constant indicates that this shared interrupt was not for the if _e1 device While the status variable has the receive complete S_Rc bit the transmit complete S_Tc bit or the adapter failure s_AF bit set and if the card has not been removed from the machine If the status variable has the s_Rc bit set callstheel rint routine to process the receive interrupt If the status variable has thes_Tc bit set callstheel tint routine to process the transmit interrupt Implementing the Interrupt Section 13 3 e Ifthestatus variablehas thes AF bit set callstheel error routine to process the error e Calls the READ STS macro to read the interrupt status again from the I O status register 13 1 5 Acknowledging the Interrupt The following code shows how the el_intr routine acknowledges the interrupt WRITE CMD sc CMD ACKINT S IL 2 Calls the WRITE _CMD macro to write data to the command port register In this call the rege member of the el_softc data structure specifies the I O handle that references the register in bus address space The acknowledge interrupt CMD_ACKINT and interrupt latch S_ 11 bits specify the data to be written 13 1 6 Transmitting Pending Frames The follow
171. structure for this device The controller number which is stored in the unit variable is used as an index into the array of el_softc data structures to determine which el_softc data structure is for this device Implementing the Initialization Section 8 1 Declares a pointer toan ifnet data structure called ifp and initializes it to the address of the ifnet data structure for this device The ifnet data structure is referenced through the is_if member of the el_softc data structure pointer The is_if nameis an alternate name for the ac_if member of the arpcom data structure Theac_if member is referred to as the network visible interface Declares the i and s variables The i variable stores the value that el_init_locked returns The s variable stores the value that splimp returns 8 1 2 Determining Whether the PCMCIA Card Is Present The following code shows how the el_init routine determines whether the PCMCIA card is still present in the system iE sc gt cardout return EIO 1 If the user has removed the PCMCIA card from the slot returns the error code EIO totheel_attach routine Theel_card_remove routine sets the cardout member 8 1 3 Setting the IPL and Obtaining the Simple Lock All network device drivers must set the interrupt priority level IPL to mask all LAN hardware interrupts Raising the PL protects the driver from interrupts on the same CPU
172. t include lt sys kernel h gt include lt sys proc h gt include lt sys sysconfig h gt 2 include lt net if h gt include lt net netisr h gt include lt net route h gt include lt netinet in h gt include lt netinet in_systm h gt include lt netinet in_ var h gt Network Device Driver Environment 1 3 inc inc inc inc inc inc inc inc inc inc inc inc inc inc ude lt netinet ip h gt ude lt netinet ip var h gt ude lt netinet if_ether h gt 3 ude lt net ether driver h gt ude lt io common devdriver h gt 4 ude lt hal cpuconf h gt ude lt kern thread h gt ude lt kern sched_prim h gt ude lt kern lock h gt ude lt io dec eisa eisa h gt 5 ude lt io dec pcemcia pemcia h gt 6 ude lt io dec pcemcia cardinfo h gt ude lt io dec netif lan_common h gt 7 ude lt io dec netif if_elreg h gt 8 Includes the ioct1 h include file which defines common ioct1 com mands The ioct1 h file is locatedin usr include sys ioctl h Includes the sysconfig h header file which defines the constants that all device drivers use during configuration The sysconfig hfileis located in usr include sys sysconfig h Includes the if ether h header file which defines the ether header data structure All network dr
173. t an unattach routine to stop the device About This Manual xiii Chapter 8 Describes how toimplement an init interface and associated routines using the if_el device driver s el_init routine as an example Chapter 9 Describes how to implement a start interface and associated routines using the if_el device driver s el_ start routine as an example Chapter 10 Describes how to implement a watchdog interface using theif _e1 device driver s el_watch routine as an example Chapter 11 Describes how toimplement a reset interface and associated routines using the if_el device driver s el_reset routine as an example Chapter 12 Describes how to implement an ioct1 interface using theif _e1 devicedriver s el_ioct1 routine as an example Chapter 13 Describes how to implement an interrupt handler using the if el device driver s el_intr interrupt handler as an example Chapter 14 Describes the sysconfigtab option entries necessary for configuring network device drivers on different bus types Related Documentation The following examples and documents supplement information in this manual Examples The directory usr examples ddk src network includes the example source files that are used throughout this manual if el c if _elreg h files and sysconfigtab Manuals The following documents provide important information that supplements the information in this manual e Installation Instructions a
174. t ctlr_ num 2 register struct el softo sc el _softc unit 3 register struct ifnet ifp amp sc gt is_if 4 register struct sockaddr_in sin 5 Declares as an argument a pointer toa controller data structure for this controller This data structure contains such information as the controller type the controller name and the current status Implementing the Autoconfiguration Support Section attach 6 1 of the controller The bus configuration code passes this initialized controller data structure to the driver s probe and attach interfaces Declares a unit variable and initializes it to the controller number for this controller This controller number identifies the specific 3Com 3C5x9 controller that is being attached The controller number is contained in the ct1r_num member of the controller data structure for this device Declares a pointer tothe el _softc data structure called sc and initializes it to the el_softc data structure for this device The controller number which is stored in the unit variable is used as an index into the array of el_softc data structures to determine which el _softc data structure is associated with this device Declares a pointer toan ifnet data structure called ifp and initializes it tothe address of the ifnet data structure for this device Declares a pointer toa sockaddr_in data structure called sin 6
175. t ifnet ifp amp sc gt is_if if multi_func_ flag 1 bzero caddr_t amp tuple data sizeof struct tuple _data_info tuple data_infop amp tuple data tuple infop struct tuple info amp tuple_data tuple _infop gt socket short card_infop gt socket_vnum tuple infop gt attributes 0 tuple _infop gt DesiredTuple 0x88 status GetFirstTuple tuple_infop if status SUCCESS tuple data_infop gt TupleOffset 0 tuple data_infop gt TupleDataMax u_short TUPLE DATA MAX status GetTupleData tuple_data_infop 5 12 Implementing the Autoconfiguration Support Section probe if status SUCCESS ee unsigned char amp ee copy for i 0 i lt sizeof struct w3_eeprom i ee tuple _data_infop gt TupleData i ee else printf el d Can t read multifunction card s eeprom n unit if sc gt ispcmcia pemcia_unregister_event_callback card_infop gt socket_vnum CARD_REMOVAL_ EVENT caddr_t el_card_remove return 0 else printf el d Can t read multifunction card s eeprom n unit if sc gt ispcmcia pemcia_unregister_event_callback card_infop gt socket_vnum CARD_REMOVAL_ EVENT caddr_t el_card_remove return 0 else L2 ed unsigned short amp ee copy for i 0 i lt sizeof struct w3_eeprom 2 i WRITE _ECR sc ECR_READ i DELAY 1000 ed READ EDR sc
176. tach routine obtains the simple lock shuts down the device and releases the simple lock s splimp 4 simple lock amp sc gt el_softc_lock 2 el_shutdown sc 3 simple unlock amp sc gt el_softc_lock 4 splx s L5 Calls the splimp routine to mask all LAN hardware interrupts Upon successful completion splimp stores an integer value in the 7 2 Implementing the unattach Routine s variable This value represents the CPU priority level that existed before the call to splimp 2 Calls the simple _lock routine to assert a lock with exclusive access for the resource that is associated with the el_softc_lock data structure This means that no other kernel thread can gain access to the locked resource until you call simple unlock to release it Because simple locks are spin locks simple _lock does not return until the lock has been obtained 3 Stops the device and puts it in a reset state 4 Callsthe simple unlock routine to release the simple lock 5 Calls the sp1x routine to reset the CPU priority to the level that is stored in the s variable 7 4 Disabling the Interrupt Handler The following code shows how the el_unattach routine disables and deletes the interrupt handler if sc gt hid 4 handler disable sc gt hid handler del sc gt hid sc gt hi
177. thdr len 3 amp 0x3 1 4 Maintains the number of bytes free in the transmit FIFO 9 2 5 Updating Counters Freeing the Transmit Buffer and Marking the Output Process as Active The following code shows how the el_start_locked routine updates counters frees the transmit buffer and marks the output process as active ADD_XMIT _PACKET ifp sc m gt m_pkthdr len 1 eh mtod m struct ether header if eh gt ether dhost 0 amp 0x1 ADD XMIT_MPACKET ifp sc m gt m_pkthdr len m_freem m 2 ifp gt if_flags IFF_OACTIVE else if m 3 IF_PREPEND amp ifp gt if_snd m break else break 1 Updates the counters using the ADD _XMIT_ PACKET and possibly the ADD _XMIT_MPACKET for multicast packets macros These macros are defined in the Lan_common h file Most network drivers perform this task in the transmit complete interface 2 Callsthem_freem routine to free the mbuf buffer Network drivers must free the buffer after the transmit operation is complete 3 If thereis no room for this transmit puts the mbuf back on the queue Implementing the Start Section 9 7 9 2 6 Indicating When to Start the Watchdog Routine The following code shows how theel_start_locked routine indicates the time for starting the driver s watchdog interface Although this task is optional we recommend that all network
178. the Ethernet unshielded twisted pair cable wires ACR_10B5 If set the information transmission rate is at 10 Mb sec for the Ethernet thick coaxial cable wire The length between repeaters is 500 meters ACR_10B2 If set the information transmission rate is at 10 Mb sec for the Ethernet thin coaxial cable wire The length between repeaters is 200 meters ACR_ROMS Represents the read only memory size for the ISA bus ACR_ROMB Represents the read only memory base for the SA bus ACR_ASE Represents the autoselect mode ACR_BASE Represents the I O base address N Defines the offset for the resource configuration register 2 6 Defining Device Register Offsets 8 Defines an enumerated data type called wo rcr Theif_el device driver can assign one of the following bits to w0_RCR the resource configuration register RCR_IRQ Represents the interrupt request IRQ RCR_RSV Represents a reserved field 9 Defines the offset for the EEPROM command register 10 Defines an enumerated data type called wo _ecr Theif_el device driver can assign one of the following bits to w0_ECR the EEPROM command register ECR_EBY Indicates that the EEPROM is busy ECR_TST Indicates that the EEPROM is in test mode ECR_CMD Represents EEPROM command bits ECR_READ Represents an EEPROM read command ECR_WRITE Represents an EEPROM write command ECR_ERASE Represents an EEPROM erase comm
179. the data returned by READ BUS D16 is not Ox6d50 calls the printf routine to display an appropriate message on the console terminal 7 Returns the value 0 zero to indicate that the probe operation failed 8 Performs tasks related to the ISA bus if bus type evaluates tothe constant BUS_ISA 9 Calls the get _config routine to obtain the base I O address for the device 10 If get_config is successful stores the base I O address in the reg variable 11 If get_config is unsuccessful calls the printf routine to display an appropriate message on the console terminal then returns the value 0 zero to indicate that the probe operation failed 12 Callsthe get config routine to obtain the interrupt request IRQ line for the device If get_config is not successful el probe calls the printf routine to display an appropriate message on the console terminal then returns the value 0 zero to indicate that the probe operation failed 13 If thisis the first ISA 3Com 3C5x9 adapter seen in the system calls the el_isa_reset_all routine to reset all 3Com 3C5x9 adapters on the ISA bus once to clear any bad state data 14 Callstheel_isa_activate routine to attempt to activate the lowest addressed adapter on the bus and to configure it with the given base address If the attempt fails el probe calls the printf routine to display an
180. ting Memory for a Test Packet The following code shows how the el_autosense thread routine allocates memory for a test packet MGETHDR m M WAIT MT_DATA if passes gt EL _AUTOSENSE PASSES m NULL if m m_freem m printf el d Autosense thread cannot determine media n ifp gt if_unit printf el d Use lan_config to configure if necessary n ifp gt if_unit else printf el d Autosense thread cannot get xmit buffer n ifp gt if_unit 5 3 8 Using the Default from the ROM The following code shows how the el_autosense thread routine uses the default media setting from ROM This code sequence signifies a last resort if the driver is unable to determine the media switch sc gt eeprom addrconf amp Oxc 1 case ACR_10B5 if sc gt lm_media_mode LAN MODE AUTOSENSE sc gt lm_media LAN MEDIA AUI break case ACR_10B2 if sc gt lm_media_mode LAN MODE AUTOSENSE sc gt lm_media LAN MEDIA BNC break case ACR_10BT default if sc gt lm_media_mode LAN MODE AUTOSENSE sc gt lm_media LAN MEDIA UTP break printf el d Used s setting from eeprom n Implementing the Autoconfiguration Support Section probe 5 21 ifp gt if_unit lan_media_strings_10 sc gt lm_ media good_xmits 100 1 Uses the default from ROM 5 3 9 Setting the Media in the Hardware The following code shows how theel_autosense_ thread routine
181. tion 5 1 11 Saves the controller and softc data structure pointers Section 5 1 12 Tries to allocate another controller data structure Section 5 1 13 Registers the shutdown routine Section 5 1 14 5 1 1 Setting Up the el_probe Routine The following code shows how to set up the el _probe routine static int el probe io_handle t io_handle 1 struct controller ctlr 2 struct el_softc sc 3 int unit ctlr gt ctlr_num i j isatag 0 status multi_func_flag 0 4 struct handler intr info el intr info 5 ihandler_ t el_ihandle 6 struct card_info card_infop struct card_info ctlr gt card_info ptr 7 io_ handle t reg 8 struct e port port_sel 9 struct irq irq_sel 10 unsigned short ed unsigned char ee struct tuple info tuple infop 11 struct tuple data_info tuple data struct tuple data_info tuple data_infop Declares an argument that specifies an 1 O handle that you can use to reference a device register or memory that is located in bus address space either I O space or memory space This O handle references the device s 1 O address space for the bus where the read operation originates in calls tothe read_io port routine and where the write operation occurs in calls tothe write io port routine The bus configurat
182. us error that requires a reset TX_MC Indicates the maximum number of colli sions that occurred TX_OF Indicates an overflow error TX_RE Not currently used Defines the offset for the request interrupt after completion register Defines the offset for the receive data register Defines the offset for the transmit data register 2 10 Defining Device Register Offsets Defines the offset for the free transmit bytes register 2 6 Window 4 Diagnostic Register Offset Definitions The window 4 operational registers include such registers as the media type and status register and the network diagnostic port register as shown in Figure 2 4 Figure 2 4 Window 4 Diagnostic Registers Media Type and Status Register W4 MEDIA Network Diagnostic and W4_NET Status Register ZK 1270U Al The following code shows the definitions for the window 4 diagnostic registers define W4_MEDIA oxa 1 enum w4 media 2 MD_TPE 0x8000 MD_COAXE 0x4000 MD_RES1 0x2000 MD_SQE 0x1000 MD_VLB 0x0800 MD_PRD 0x0400 MD_JAB 0x0200 MD UNSQ 0x0100 MD_LBE 0x0080 MD_JABE 0x0040 MD_CS 0x0020 MD_COLL 0x0010 MD SQEFE 0x0008 MD_NCRC 0x0004 i define W4_NET ox6 3 enum w4_net 4 ND_EXT 0x8000 ND_ENDEC 0x4000 ND_ECL 0x2000 ND_LOOP 0x1000 ND_TXE 0x0800 ND_RXE 0x0400 ND_TXB 0x0200 ND_TXRR 0x0100 ND_STATE 0x0080 ND_REV 0x003e
183. work interfaces you can specify a different counter type and a different set of counters Table 12 2 lists the types of counters that the various network interfaces support Table 12 2 Network Interface Counter Types Network Interface Counter Types FDDI Token Ring FDDI interface statistics Status information SMT attributes MAC attributes Path attributes Port attributes SMT MIB attributes Extended MIB attributes Compaq proprietary Characteristics Counters MIB counters MIB statistics Bringing Up the Device SIOCSIFADDR ioctl Command The following code shows how the el_ioct1 routine implements the SIOCSIFADDR ioctl command to bring up the device case SIOCSIFADDR ifp gt if_flags IFF_UP 2 el_reset_locked sc if sc gt ztime 0 sc gt ztime time tv sec 3 break 1 ifp unit 1 Determines whether the cmd argument is SIOCSIFADDR Implementing the ioctl Section 12 9 Marks the interface as up and calls the el reset locked routine to start the network interface with the current settings Sets the counter cleared time used by DE Cnet netstat clusters and so forth 12 12 Using Currently Set Flags SIOCSIFFLAGS ioctl Command The following code shows how the el_ioct1 routine implements the SIOCSIFFLAGS ioct1 command to reset the device using currently set flags case SIOCSIFFLAGS i
184. x4 7 define CMD_WINDOW5 Ox1l lt lt 11 0x5 8 define CMD_WINDOW6 Ox1 lt lt 11 0x6 9 define CMD_START2 Ox2 lt lt 11 10 define CMD _RXDIS 0x3 lt lt 11 11 define CMD_RXENA 0x4 lt lt 11 12 define CMD _RXRESET Ox5 lt lt 11 13 define CMD _RXDTP Ox8 lt lt 11 14 define CMD_TXENA Ox9 lt lt 11 15 define CMD _TXDIS Oxa lt lt 11 16 define CMD_TXRESET Oxb lt lt 11 17 define CMD_REQINT 0xc lt lt 11 18 define CMD_ACKINT Oxd lt lt 11 19 define CMD_SINTMASK Oxe lt lt 11 20 define CMD_ZINTMASK Oxf lt lt 11 21 define CMD FILTER 0x10 lt lt 11 22 enum rx filter 23 RF_IND 0x1 RF_GRP 0x2 RF_BRD 0x4 RF_PRM 0x8 ya define CMD_RXEARLY Ox1ll lt lt 11 24 define CMD_TXAVAILTHRESH Ox12 lt lt 11 25 define CMD_TXSTARTTHRESH 0x13 lt lt 11 26 define CMD_STATSENA Ox15 lt lt 11 27 define CMD _STATSDIS 0x16 lt lt 11 28 define CMD_STOP2 Ox17 lt lt 11 29 define CMD _RXRECTHRESH 0x18 lt lt 11 30 2 2 Defining Device Register Offsets define CMD_POWERUP Oxlb lt lt 11 31 define CMD POWERDOWN 0x1c lt lt 11 32 define CMD_POWERAUTO 0x1d lt lt 11 33 1 Defines the offset for the I O port of the command port register 2 Defines the reset command bit position 3
185. you call simple unlock toreleaseit Because simple locks are spin locks simple lock does not return until the lock has been obtained Enabling Loopback Mode SIOCENABLBACK ioctl Command The following code shows how the el_ioct1 routine implements the SIOCENABLBACK ioctl command to enable loopback mode when an application requests it Support for the STOCENABLBACK command is optional You can choose whether or not your driver supports it switch cmd 4 case SIOCENABLBACK 2 ifp gt if_flags IFF_LOOPBACK 3 if ifp gt if_flags amp IFF_RUNNING 4 el_reset_locked sc ifp unit break 1 Evaluates the value passed in through the cmd argument to determine which ioct1 command the caller has requested 2 Determines whether the cmd argument is SIOCENABLBACK 3 Sets the IFF_LOOPBACK bitin theif flags member of the ifnet data structure for this device 4 If the deviceis running calls the el reset locked routineto restart the network interface in loopback mode Disabling Loopback Mode SIOCDISABLBACK ioctl Command The following code shows how the el_ioct1 routine implements the SIOCDISABLBACK ioct1 command to disable loopback mode when an application requests it Support for the SIOCDISABLBACK command is optional However if your driver supports SITOCENABLBACK it must support SIOCDISABLBACK case SIOCDISABLBACK 1 ifp gt if_

Compaq AA-PWCBD-TE Computer Accessories User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents