Compaq TRU64 AA-RNG2A-TE Manual de usuario

Tru64 UNIXWriting Network Device DriversPart Number: AA-RNG2A-TEDecember 2000Product Version: Device Driver Kit Version 2.0Operating System and Versio

8Implementing the Initialization SectionThe initialization section prepares the network interface to transmit andreceive data packets. It can also all

3 Declares a pointer to an ifnet data structure called ifp and initializesit to the address of the ifnet data structure for this device. Theifnet data

The el_softc_lock member of the el_softc data structure points toa simple lock data structure. The if_el device driver declares this datastructure by

• Sets the LAN media type attribute (Section 8.2.6)• Selects memory mapping (Section 8.2.7)• Resets the transmitter and receiver a second time (Sectio

This task is specific to the 3Com 3C5x9 device. Make sure that you performsimilar initialization tasks for the hardware device that your network drive

8.2.5 Setting the LAN MediaThe following code shows how the el_init_locked( ) routine sets theLAN media. This task is specific to the 3Com 3C5x9 devic

10 For the default case, sets the lm_media member to LAN_MEDIA_UTP(media mode is unshielded twisted pair cable).11 Determines whether lm_media evaluat

WRITE_CMD(sc, CMD_TXRESET); 1WRITE_CMD(sc, CMD_RXRESET); 21 Calls the WRITE_CMD macro to write data to the command portregister. The data to be writte

else {lan_set_attribute(sc->ehm.current_val, NET_PROMISC_NDX, (void *)0);}WRITE_CMD(sc, CMD_FILTER+i);71 If loopback mode is requested, enables it.

About This ManualThis manual discusses how to write network device drivers for computersystems that run the Compaq Tru64™ UNIX operating system.Audien

WRITE_CMD(sc, CMD_RXENA); 1WRITE_CMD(sc, CMD_TXENA); 21 Calls the WRITE_CMD macro to write data to the command port register.The data to be written is

ifp->if_flags |= IFF_RUNNING; 1ifp->if_flags &= ~ IFF_OACTIVE; 21 Sets the IFF_RUNNING flag to mark the device as running.2 Clears the IFF_O

9Implementing the Start SectionThe start section of a network device driver transmits data packets acrossthe network. When the network protocol has a

2 Calls the simple_lock_try( ) routine to try to assert a lock with readand write access for the resource that is associated with the specifiedsimple

This simple lock was previously asserted by calling the simple_lock( )or simple_lock_try( ) routine.2Calls the splx( ) routine to reset the CPU priori

IF_DEQUEUE(&ifp->if_snd, m); 3while (m) { 4m_freem(m);IF_DEQUEUE(&ifp->if_snd, m);}return;}1 Declares a pointer to an ether_header data

mp = ms; 8mn = mp->m_next; 9len = mp->m_len; 10while (mn != NULL) { 11if (mn->m_len == 0) {mp->m_next = mn->m_next;mn->m_next = NULL

in the middle. The mfree( ) routine is called to free any zero-lengthmemory buffers.12Otherwise, adds the length and sets the next memory buffer in th

2 Copies transmit data from memory to the card using 32-bit writes. Onlya multiple of 4 bytes can be copied this way.3 If some number of bytes (fewer

• Socket and XTI programming examples• TCP specific programming information• Information for Token Ring driver developers• Data link interfaceSee the

9.2.6 Indicating When to Start the Watchdog RoutineThe following code shows how the el_start_locked( ) routine indicatesthe time for starting the driv

10Implementing a Watchdog SectionNetwork device drivers can take advantage of the watchdog timer. Thenetwork layer implements this mechanism to ensure

2 Calls the simple_lock( ) routine to assert a lock with exclusive accessfor the resource that is associated with the el_softc_lock simple lockdata st

11Implementing the Reset SectionThe reset section of a network device driver contains the code that resets theLAN adapter when there is a network fail

3 Calls the el_reset_locked( ) routine, which performs the actualtasks that are associated with resetting the device.4 Calls the simple_unlock( ) rout

12Implementing the ioctl SectionThe ioctl section of a network devicedriver contains the code that implementsa network device driver’s ioctl interface

Table 12–1: Network ioctl Commands (cont.)ioctl CommandRequired Description For More InformationSIOCSIFFLAGSYes Ensures that theinterface is operating

7 Casts the data argument to a data structure of type ifdevea for usewith the SIOCRPHYSADDR ioctl command.8 Casts the data argument to a data structur

you call simple_unlock( ) to release it. Because simple locks are spinlocks, simple_lock( ) does not return until the lock has been obtained.12.4 Enab

12.6 Reading Current and Default MAC Addresses(SIOCRPHYSADDR ioctl Command)The following code shows how the el_ioctl( ) routine implements theSIOCRPHY

New and Changed FeaturesThis revision of the manual documents the following new features:• Enabling support for enhanced hardware managementEnhanced h

4 If the 3Com 3C5x9 device is running, calls the el_reset_locked( )routine to restart the network interface with the new address.5 Calls the simple_un

ether_sprintf(maddr),sc->is_multi.lan_mtable[j-1].muse);}}lan_build_mclist (mclist_buf, NET_SZ_MCLIST, &sc->is_multi);5lan_set_attribute(sc-

if (sc->debug) {j=0;printf("el%d: Dump of multicast table after DEL (%d entries)\n",unit, sc->is_multi.lan_nmulti);for (i=0; i<sc-&

2 Copies the current counters to the ctrreq data structure.3 Indicates that these are Ethernet counters.4 Returns the number of seconds since the coun

2 Marks the interface as up and calls the el_reset_locked( ) routineto start the network interface with the current settings.3 Sets the counter cleare

SIOCSMACSPEED and SIOCIFSETCHAR ioctl commands perform some ofthe same tasks.)case SIOCSMACSPEED: 1bcopy(ifr->ifr_data, (u_char *)&speed, sizeo

if (ifc->ifc_auto_sense != -1) { 5if ((ifc->ifc_auto_sense == LAN_AUTOSENSE_ENABLE) &&(sc->lm_media_mode != LAN_MODE_AUTOSENSE)) {sc-

If the user sets media that the card does not have, the interface maynot work.9Selects the new mode.10 Resets the device to pick up the new mode (if t

13Implementing the Interrupt SectionThe interrupt section of a network device driver contains the code that iscalled whenever the network interface tr

Chapter 8 Describes how to implement an initinterface and associated routines, usingthe if_el device driver’s el_init( )routine as an example.Chapter

13.1.1 Setting the IPL and Obtaining the Simple LockThe following code shows how the el_intr( ) routine sets the CPU’s IPLand obtains the simple lock:

13.1.3 Reading the Interrupt StatusThe following code shows how the el_intr( ) routine uses the READ_STSmacro to read the interrupt status from the I/

• If the status variable has the S_AF bit set, calls the el_error( )routine to process the error.• Calls the READ_STS macro to read the interrupt stat

13.1.8 Indicating That the Interrupt Was ServicedThe following code shows how the el_intr( ) routine indicates that theinterrupt was serviced:return I

13.2.2 Pulling the Packets from the FIFO BufferThe following code shows how the el_rint( ) routine pulls the packetsfrom the first-in/first-out (FIFO)

2 Looks for errors.3 Processes the error.4 Processes the overrun error case.5 Processes the runt and oversized error cases.6 Processes the CRC error c

if (bcmp(mtod(m, unsigned char *),etherbroadcastaddr, 6) != 0) {8int ix;LAN_FIND_MULTI(&sc->is_multi,mtod(m, unsigned char *),ix, i);9if ( (i !

eh = *(mtod(m, struct ether_header *)); 2eh.ether_type = ntohs((unsigned short)eh.ether_type); 3m->m_data += sizeof(struct ether_header); 4ADD_RECV

if ((sc->debug) && (count <= 0))printf("el%d: Receive in INFINITE loop %04X\n", ifp->if_unit, status);}1 Calls the WRITE_CM

WRITE_CMD(sc, CMD_TXRESET);DELAY(10);4WRITE_CMD(sc, CMD_TXENA);1 Calls the READ_TXS macro to read the transmit status from thetransmit status register

• Writing Device Drivers contains information that you need to developdevice drivers on the Compaq Tru64 UNIX operating system.• Writing Kernel Module

2 Updates the softc data structure with the amount of space that isavailable in the transmit FIFO.13.3.5 Queuing Other TransmitsThe following code sho

14Network Device Driver ConfigurationDevice driver configuration incorporates device drivers into the kernel tomake them available to system administr

IndexNumbers and SpecialCharacters10Base2 transceiverensuring that it is off,8–5Aallocating the ether_driver datastructure,5–7attach interface,6–1regi

of pending transmit frames,13–4of receive interrupt,13–8debug flag,3–8setting,8–9debug informationprinting,5–24declarationsconfigure-related,4–2networ

initializing the enhanced hardwaremanagement data structure,5–8performing bus-specific tasks,5–4registering interrupt handlers,5–15registering the shu

interrupt handlerenabling,6–10ID,3–6registering,5–15interrupt section,1–11implementing,13–1ioctl commandSIOCADDMULTI,12–6SIOCDELMULTI,12–7SIOCDISABLBA

autoconfiguration support section,1–10configure section,1–10declarations,1–4environment,1–1include files,1–3initialization section,1–10interrupt secti

ROMusing the default from,5–21RX statusreading,13–5Ssectionautoconfiguration support,1–10,5–1, 6–1configure,1–10declarations,1–4include files,1–3initi

loading into the buffer,5–22transmitting,5–22timeoutinformation in el_softc datastructure,3–9rearming the next,13–2timerclearing,10–2transmitcounting

• Internet electronic mail: [email protected] Reader’s Comment form is located on your system in the followinglocation:/usr/doc/readers_com

that are used in driver configuration, these bracketsindicate items that are optional.| Vertical bars separating items that appear in thesyntax defini

1Network Device Driver EnvironmentA network device is responsible for both transmitting and receiving framesover the network media. Network devices ha

© 2000 Compaq Computer CorporationCompaq and the Compaq logo Registered in U.S. Patent and Trademark Office. Tru64 is a trademark ofCompaq Information

Figure 1–1: Sections of a Network Device Driver/* Include Files Section *//* Configure Section *//* Autoconfiguration Support Section *//* Start Trans

Instead of registering its entry points in a dsent data structure, a networkdriver registers its entry points with the upper layers of the Tru64 UNIXo

#include <netinet/ip.h>#include <netinet/ip_var.h>#include <netinet/if_ether.h>3#include <net/ether_driver.h>#include <io/c

• External and forward declarations (Section 1.2.1)• Declaration of softc and controller data structure arrays(Section 1.2.2)• Declaration of the driv

4 Declares a pointer to the external task_t data structure calledfirst_task. The task_t data structure is an opaque data structure;that is, all of its

1.2.3 Declaring and Initializing the driver Data StructureThe following code shows how the if_el device driver declares andinitializes the driver data

READ_BUS_D8Reads a byte (8 bits) from a device register.READ_BUS_D16Reads a word (16 bits) from a device register.READ_BUS_D32Reads a longword (32 bit

The second argument to the WRITE_CCR and the other write macrosspecifies the data to be written to the device register in bus addressspace. These writ

Table 1–1: Driver-Specific Macros (cont.)Macro DescriptionREAD_RXSRead from the 3Com 3C5x9 device’s receive statusregister.READ_FDPRead from the 3Com

1.7 Watchdog Section for a Network DriverThe watchdog section for a network device driver contains a watchdoginterface, which attempts to restart the

ContentsAbout This Manual1 Network Device Driver Environment1.1Include Files Section for a Network Driver ... 1–31.2Declarations S

interface to transmit the data. All network drivers must set the outputmember of the ifnet data structure to ether_output.1–12 Network Device Driver E

2Defining Device Register OffsetsThe device register header file defines the device register offsets for thedevice. The if_elreg.h file is the device

2 Defines the interrupt latch bit position.3 Defines the adapter failure bit position.4 Defines the transmit complete bit position.5 Defines the trans

#define CMD_POWERUP (0x1b<<11) 31#define CMD_POWERDOWN (0x1c<<11) 32#define CMD_POWERAUTO (0x1d<<11) 331 Defines the offset for the

23 Defines an enumerated data type called rx_filter. The if_el devicedriver can assign one of the following values to CMD_FILTER:RF_INDIndividual addr

Figure 2–1: Window 0 Configuration RegistersRegisterManufacturer ID RegisterZK-1267U-AIConstantW0_MIDAdapter ID RegisterW0_AIDConfiguration Control Re

ECR_WRITE=0x0040,ECR_ERASE=0x00c0,ECR_EWENA=0x0030,ECR_EWDIS=0x0000,ECR_EAR= 0x0020,ECR_WAR= 0x0010};#define W0_EDR 0xc111 Defines the offset for the

8 Defines an enumerated data type called w0_rcr. The if_el devicedriver can assign one of the following bits to W0_RCR (the resourceconfiguration regi

Figure 2–2: Window 3 Configuration RegistersRegisterAdditional Setup Information2 RegisterZK-1268U-AIConstantW3_ASI2Additional Setup Information0 Regi

ASI_RSIZE8Indicates a RAM size of 8 kilobytes (the default).ASI_RSIZE32Indicates a RAM size of 32 kilobytes.2.5 Window 1 Operational Register Offset D

3.6Defining the Interrupt Handler ID ...3–63.7Defining CSR Pointer Information ...3–63.8De

};#define TX_INT 0x80005#define W1_RXDATA 0x0 6#define W1_TXDATA 0x0 7#define W1_FREETX 0xc 81 Defines the offset for the receive status register.2 De

8 Defines the offset for the free transmit bytes register.2.6 Window 4 Diagnostic Register Offset DefinitionsThe window 4 operational registers includ

2 Defines an enumerated data type called w4_media. The if_el devicedriver can assign one of the following values to W4_MEDIA (the mediatype and status

2.7 EEPROM Data Structure DefinitionThe following code shows the definition for the w3_eeprom data structure.This data structure stores information ab

3Defining the softc Data StructureAll network device drivers define a softc data structure to contain thesoftware context of the network device driver

Figure 3–1: Typical softc Data StructureCommon InformationMedia State InformationEnhanced Hardware Management InformationBase RegisterMulticast Table

#define is_ac is_ed->ess_ac 2#define ztime is_ed->ess_ztime 3#define ctrblk is_ed->ess_ctrblk 4#define is_if is_ac.ac_if 5#define is_addr is_

Figure 3–2: Mapping Alternate NamesZK-1274U-AI#define is_ac ess_ac#define ztime#define is_if #define ac_enaddr#define ctrblk#define is_addr...es

lan_media_mode usually reflects how the media is to be selected. (Incontrast, the value that is stored in the lan_media member reflects thecurrent set

5.3.5Entering the Packet Transmit Loop ... 5–205.3.6Saving Counters Prior to the Transmit Operation ... 5–215.3.7Alloca

member in the driver’s probe interface to the media state constant thatidentifies the state for the media.You can set the lan_media member to the same

access a CSR directly. The driver-specific macros handle the read and writeoperations that are made on these device registers.The following code shows

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

The following code shows the declarations of the timeout and interruptinformation in the if_el device driver’s el_softc data structure:unsigned long t

3.15 Defining a Copy of the w3_eeprom Data StructureThe w3_eeprom data structure copy in the if_el driver’s el_softcdata structure consists of informa

4Implementing the Configure SectionThe configure section of a network device driver contains the codethat incorporates the device driver into the kern

The following code shows the declaration of the variables and theinitialization of the cfg_subsys_attr_t data structure for the if_eldevice driver:sta

6 Declares the lan_config_data structure, which contains allinformation specific to the el driver. The lan_configure commoncode uses this structure.7

represents a variety of information, including the if_el driver’sinterrupt polling requirements.3Declares an argument called indatalen to store the si

5Implementing the AutoconfigurationSupport Section (probe)The autoconfiguration support section contains the code that implements anetwork device driv

7.10Unregistering the Card from the Hardware ManagementDatabase ...7–57.11Freeing Resource

• For subsequent probe operations, reads the EEPROM to determine if thehardware address (and thus the adapter) has changed (Section 5.1.10)• Registers

contained in the ctlr_num member of the controller data structurefor this 3Com 3C5x9 device.5Declares a handler_intr_info data structure called el_int

5.1.2 Checking the Maximum Number of Devices That the DriverSupportsThe following code shows how to check for the maximum number of devicesthat the if

case BUS_ISA: 8if (get_config(ctlr, RES_PORT, NULL, &port_sel, 0) >= 0) { 9reg = port_sel.base_address; 10} else { 11printf("el%d: Can’t g

6 Calls the READ_BUS_D16 macro a second time to determine whetherthe EtherLink III is attached. If the data returned by READ_BUS_D16is not 0x6d50, cal

if (el_softc[unit]) { 1sc = el_softc[unit];sc->cardout = 0;sc->reprobe = 1;} else {2MALLOC(sc, void*, sizeof(struct el_softc), M_DEVBUF, M_WAIT

2 Initializes all Ethernet statistics counters in the ether_driver datastructure to 0 (zero).5.1.6 Initializing the Enhanced Hardware Management Data

sc->irq = 3; 3sc->iobase = 0; 4sc->ispcmcia = 1; 5sc->cinfop =card_infop;pcmcia_register_event_callback(card_infop->socket_vnum,6CARD_R

5.1.9 Handling First-Time Probe OperationsIf the device has not already been probed, the el_probe( ) routine performsthe following tasks:• Reads the E

for (i=0; i<(sizeof(struct w3_eeprom)/2); i++) {WRITE_ECR(sc, ECR_READ+i);DELAY(1000);*ed = READ_EDR(sc);ed++;}}for (i=0; i<3; i++) {4j = sc->

9.2.3Transmitting the Buffer ...9–69.2.4Accounting for Outgoing Bytes ...9–79.2.5U

8 Calls the kernel_thread_w_arg( ) routine to create and start akernel thread with timeshare scheduling. A kernel thread that iscreated with timeshare

if (status == SUCCESS) {ee = (unsigned char *)&ee_copy;for (i = 0; i < (sizeof(struct w3_eeprom)); i++) {*ee = tuple_data_infop->TupleData[i

bcopy(&ee_copy, &sc->eeprom, sizeof(struct w3_eeprom)); 11}}1 If this is a multifunction card, reads the EEPROM data and savesit in a tempo

registration of interrupt handlers. All network device drivers are required toregister interrupt handlers.el_intr_info.configuration_st = (caddr_t)ctl

This routine returns an opaque ihandler_id_t key, which is aunique number that identifies the interrupt handler to be actedon by subsequent calls to h

5.1.14 Registering the shutdown RoutineThe following code shows how the el_probe( ) routine registers itsshutdown( ) routine. The kernel calls this ro

To determine the mode, el_autosense_thread( ) tries to send a test datapacket in each of the possible modes. When it successfully transmits the datapa

• Determines whether packets were transmitted successfully(Section 5.3.14)• Prints debug information (Section 5.3.15)• Sets up new media to try if tra

5.3.3 Testing for the Termination FlagThe following code shows how the el_autosense_thread( ) routine testsfor the termination flag:while (thread_shou

simple_unlock(&sc->el_softc_lock);splx(s);thread_halt_self();}1 Enters a loop for transmitting a packet and determining if it succeeds.A packet

12.15Resetting the Device (SIOCIFRESET ioctl Command) ... 12–1112.16Setting Device Characteristics (SIOCIFSETCHAR ioctlCommand) ...

ifp->if_unit, lan_media_strings_10[sc->lm_media]);good_xmits = 100;1 Uses the default from ROM.5.3.9 Setting the Media in the HardwareThe follow

5.3.12 Setting a Timer for the Current Kernel ThreadThe following code shows how the el_autosense_thread( ) routine sets atimer for the current kernel

WRITE_CMD(sc, CMD_WINDOW1);simple_unlock(&sc->el_softc_lock);splx(s);break;default:break;}1 Tests for loss of carrier errors. Most network adap

if (sc->lm_media_mode == LAN_MODE_AUTOSENSE)sc->lm_media = LAN_MEDIA_UTP;break;case LAN_MEDIA_BNC:if (sc->lm_media_mode == LAN_MODE_AUTOSENSE

Because simple locks are spin locks, simple_lock( ) does not returnuntil the lock has been obtained.The el_softc_lock member of the el_softc data stru

6Implementing the AutoconfigurationSupport Section (attach)The autoconfiguration support section implements a network device driver’sattach interface.

of the controller. The bus configuration code passes this initializedcontroller data structure to the driver’s probe and attachinterfaces.2Declares a

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 follo

3 Sets the if_mtu member of the ifnet data structure for this device tothe maximum transmission unit, which for Ethernet-related media isrepresented b

8 Sets the sin_family member of the sockaddr_in data structure tothe address family, which in this case is represented by the constantAF_INET. The soc

2–4Window 4 Diagnostic Registers ...2–113–1Typical softc Data Structure ...3–23

6.5 Printing a Success MessageThe following code shows how the el_attach( ) routine prints a successmessage:printf("el%d: %s, hardware address: %

3 Sets the if_start member of the ifnet data structure for this deviceto el_start, which is the if_el device driver’s start transmit foroutput interfa

8 Sets the if_version member of the ifnet data structure for thisdevice to the string 3Com EtherLink III.6.7 Setting the Baud RateThe following code s

2 Calls the if_attach( ) routine to attach an interface to the list ofactive interfaces. The argument to the if_attach( ) routine is apointer to the i

6.11 Enabling the Interrupt HandlerThe following code shows how the el_attach( ) routine enables theinterrupt handler:handler_enable(sc->hid); 11Ca

7Implementing the unattach RoutineThe el_unattach( ) routine is called to stop the device and to free memoryand other resources prior to unloading the

struct el_softc *sc = el_softc[unit];struct ifnet *ifp = &sc->is_if;1 Declares as an argument a pointer to a bus data structure and acontroller

s variable. This value represents the CPU priority level that existedbefore the call to splimp( ).2Calls the simple_lock( ) routine to assert a lock w

7.6 Unregistering the PCMCIA Event Callback RoutineThe following code shows how the el_unattach( ) routine unregistersthe PCMCIA event callback routin

7.10 Unregistering the Card from the HardwareManagement DatabaseThe following code shows how the el_unattach( ) routine unregisters thecard from the h