13,044,115 members (64,289 online)
alternative version

#### Stats

63.6K views
40 bookmarked
Posted 14 Mar 2008

# NDIS sample - 6.0 miniport driver for realtek 8168/8169/8111/8110

, 1 May 2008
 Rate this:
NDIS 6.0 miniport driver for realtek 8168/8169/8111/8110 family of gigabit ethernet controllers

## Introduction

For those who aspire to write an NDIS 6.0 miniport windows ( Desktop PFs ) device driver for a new or existing ethernet controller, the only sample source code available is the E100BEX found in the Microsoft DDK. There are a couple of other type of NDIS drivers like IM available in the net, but not any miniport drivers for a NIC, AFAIK.

The E100BEX sample, hereafter referred to as e100, is for the intel line of etherexpress 100Mbs NIC cards. So if one wants to understand this e100 by live debugging, apart from static code analysis, he/she has to have this type of card, which is rarely found nowadays IMO.

So, I thought, why not write an NDIS 6 driver for a different popular ethernet controller easily found nowadays. I chose the Realtek family of gigabit ethernet controllers 8111/8168/8169/8110 found as a PCI card cheaply around \$9 ( brands like hawkings, startech )and also as LOM ( Lan On Motherboard ) in many of the modern motherboards.

## Background

The approach I took was -- Instead of starting from scratch, port the Microsoft DDK sample e100, from intel to realtek h/w.
The benefit is -- The well tested e100 core and NDIS-related logic, the various state-machines, various synchronization mechanisms are ALL retained and only the h/w portions are changed.

Well, easier said than done. For one thing, though e100 is well designed/written, somehow I feel, the NDIS code seems to be tightly coupled with the h/w related code. Understandable from a performance point of view. Other, the intel h/w and drivers are designed to work mostly on linked-list data structures shared between host and device, whereas the realtek h/w seems to be ARRAY oriented. So, the challenge is to adapt e100 meant for linked-lists to array oriented, without changing any of the original code's logic flow.

DDK build 6001, e100 sample was used as the baseline. Later some portions from the windows 2008 server DDK e100 sample were taken and merged to fix a SEND issue. More on this later.

### Code workings

I hope the ample comments found in the original e100 and my own added comments should be sufficient to explain things. Still as i get more time, i will keep adding more and more to this section.
The original e100bex.htm may be a starting point

### BUILD instructions

* DDK build 6000 was used. A straight forward command-line "build -cZ" will do. No batch files

### INSTALL instructions

The standard unsigned-driver installation way, using the provided RLTK1GIG.INF file

Still for newbies -- Go to DM, select the realtek network device and right click option "update driver". Keep going to the end the manual way, w/o letting the wizard take control of the process anytime.

### Test results

• The driver was tested under VISTA32 free version, under heavy network load/stress conditions. It performed well without any crashes for hours together continuosly. I wish i could test more rigorously with sophisticated test tools and in a chatty network environment, but since i dont have them, hope somebody will provide such test results later to this forum. I also wish i could use "NDISTEST" from Microsoft WLK ( older term - HCT ) but unfortunately as many know the DTM controller can only be run on server 2003. Why microsoft made it this way, effectively alienating the smaller/individual/non-corporate device driver developers, is anybody's guess.
• I tested this driver for the popular 2 of the realtek family of gigabit ethernet controllers. One, a hawkings PCI card having realtek 8169s and the other, a GIGABYTE-G33 board which has a realtek 8111b as LOM. SUCCESS. NO known issues so far.

NOTE - I tested for both 100M and 1G links.

### Disclaimer

Obviously this cannot be used for production environments. Just for informational and learning purposes. This author is not responsible for any of the consequences of using this code by anybody

• VLAN

None so far.

### misc notes

• 64-bit readiness -- This code compiles for 64-bit though i havent tested in VISTA64. I will keep you posted of the results when i do that.

UPDATE : 64-bit driver works fine in vista64. But, this INF file, i have to modify for both 32 & 64 PFs, in the future. So, time being replace the 32-bit rltkgbit.sys w/ 64-bit rltkgbit.sys, before installation and use the same INF file.

• The realtek h/w datasheet used to create this driver can be found on the internet. It can also be obtained from realtek w/ a simple email. I got one from realtek with the simple message "...you should not reveal to others..." No complicated NDAs, just a simple assurance to them that you will not make it public w/o their permission.

Otherwise the realtek 8139 data sheet available here

http://www.datasheet4u.com/html/R/T/L/RTL8139DL_RealtekMicroelectronics.pdf.html comes close to understanding this sample, atleast for send/receive operations.

## UPDATE

For all these new UPDATES I switched to the latest W2008Server 6001.18000 DDK

LSO, also referred to as Task-send-ofload ( TSO ). All the relevant code can be found under the conditional compilation directive #if OFFLOAD

Steps needed

### Step 1.

NdisMSetMiniportAttributes(.,.,.) MUST be done by initializing a NDIS_TCP_LARGE_SEND_OFFLOAD_V1 structure. This is done in MPInitialize ( .,.,.) through InitLSO ( Adapter ) ;

 /*** Initialize NDIS_OFFLOAD ****/

//
//
LsoV1->IPv4.Encapsulation = NDIS_ENCAPSULATION_IEEE_802_3 ;
//
//
NdisZeroMemory (
);
(PNDIS_MINIPORT_ADAPTER_ATTRIBUTES)&OffloadAttributes);

### Step 2.

* If we dont return NDIS_STATUS_SUCCESS, we will not get any BIG packets from NDIS to be LSO-ed.

Here is the code

#if OFFLOAD
{
//
// Verify the length
//
{
return(NDIS_STATUS_INVALID_LENGTH);
}
if ( NDIS_OFFLOAD_SET_ON == Encap->IPv4.Enabled )
Encap->IPv4.EncapsulationType = NDIS_ENCAPSULATION_IEEE_802_3 ;
Status = NDIS_STATUS_SUCCESS ;
break ;
}
#endif
#if OFFLOAD

### Step 3.

When NDIS calls MPSendNetBufferLists ( .,.,..) to send NBL, use the SCRATCH area in the NBL to store some context info about the LSO.
Here is the code

// and initialize some LSO related fields there
MoveLSOinfoFromNBLtoContext ( Adapter, CurrNetBufferList )

This function retrieves 2 main items from the NBL ; MSS and TcpHeaderOffset and saves them in a private context area ( NBL->SCRATCH )

### Step 4

NDIS 6.0 miniport is supposed to return "TcpPayLoad" in the NBL when it completes(sending) it. But since rtl8169 h/w does NOT return this value ( AFAIK ) , we have to figure it out from the NBL ( NB ) data, before sending it to the H/W. The way we do this is

Here is the code

#if OFFLOAD
PeekTcpHeader ( pMpTcb->NetBufferList, pMpTcb->NetBuffer ) ;
#endif

### Step 5

Program the h/w by setting MSS value and LGSEN bit in the realtek 8169 H/W Transmit Buffer Descriptor

#if OFFLOAD
if ( bLSOenabled ) {
pHwTbd->status |= (LGSENbit | pNBLcontext->MSS) ;

}
#endif

### Step 6

In send-complete interrupt handler set "TcpPayLoad" in the completed NBL for upper layers' consumption

#if OFFLOAD
#endif

Nothing great. just this. No changes to the H/W for send/receive

#if JUMBO_FRAME_SUPPORT
#define NIC_MAX_RECV_FRAME_SIZE 6464
#else
#define NIC_MAX_RECV_FRAME_SIZE 1664
#endif
#define NIC_MAX_XMIT_FRAME_SIZE 7040 // multiple 0f 64
#else
#define NIC_MAX_XMIT_FRAME_SIZE 1664
#endif

Nothing done to the H/W at D0 & D3 transition time. We simply indicate to the NDIS we are capable.

pPower_Management_Capabilities->Flags = NDIS_DEVICE_WAKE_UP_ENABLE ;
pPower_Management_Capabilities->WakeUpCapabilities.MinMagicPacketWakeUp = NdisDeviceStateD3;
pPower_Management_Capabilities->WakeUpCapabilities.MinPatternWakeUp = NdisDeviceStateUnspecified;
*pulInfoLen = sizeof (*pPower_Management_Capabilities);
*pStatus = NDIS_STATUS_SUCCESS;
}

TEST : MAGIC packet WOL worked fine with this code

• Though this program is copyLEFT and free to be used anywhere, I retained the copyright notices of INTEL and MICROSOFT found in the original source code. Anyway, since e100 is part of the DDK sample for public use, the copyright may not be stringent. Please refer to the original e100bex DDK sample code for copyright issues. I am not responsible
• Thanks to the linux developer community, i borrowed the initial chip MAC/PHY configuration code from the realtek linux driver and to fairly credit them, I named those files linux_init.c and linux_h.h. I am not sure how GNU licensing will affect this project FREE license, as i meant it to be.

### Finally

Any form of comments and suggestions are welcome to this forum or to alex_@esdsinc.com
remove underscore.

Cheers & good luck

## History

• first release dated 14 march 2008. version 6.0.6000.31308
• second release dated 1 May 2008. Version 6.0.6000.050108. LSO and jumbo support added
• Third release dated 2 May 2008. Version 6.0.6000.050208. Power managment capabilities added

## Share

 Software Developer (Senior) United States
passionate windows device driver developer

## You may also be interested in...

 First Prev Next
 broken link Manoj Singhii27-Dec-16 14:20 Manoj Singhii 27-Dec-16 14:20
 My vote of 4 Amir Mohammad Nasrollahi9-Aug-13 20:10 Amir Mohammad Nasrollahi 9-Aug-13 20:10
 dma buffer zxyzxzy25-Jun-13 0:32 zxyzxzy 25-Jun-13 0:32
 Re: dma buffer rgraham827-Jun-13 4:01 rgraham8 27-Jun-13 4:01
 Help in understanding NDIS User17999-Dec-12 13:59 User1799 9-Dec-12 13:59
 how to lad it in win 7 64 bit? zaganic4-Feb-11 23:45 zaganic 4-Feb-11 23:45
 Re: how to lad it in win 7 64 bit? wangyongbogood2-Apr-13 1:41 wangyongbogood 2-Apr-13 1:41
 Complie error in Windows DDK 2600 & WDK 7600.16385.1 at WinXp itechnology25-Oct-10 8:38 itechnology 25-Oct-10 8:38
 virtual NDIS miniport driver stuyckp15-Feb-10 10:13 stuyckp 15-Feb-10 10:13
 RLTKGBIT.sys not in zip file kunhao17-Mar-09 5:05 kunhao 17-Mar-09 5:05
 Re: RLTKGBIT.sys not in zip file alexander suresh30-Mar-09 8:02 alexander suresh 30-Mar-09 8:02
 Thank you so much Member 257690730-Oct-08 20:41 Member 2576907 30-Oct-08 20:41
 Last Visit: 31-Dec-99 18:00     Last Update: 21-Jul-17 6:15 Refresh 1