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


Download - 91.88 KB
Download - 91.65 KB


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.


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.

About the sample

About the driver
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.

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

Future and feature additions planned

Known issues
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 " 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 comes close to understanding this sample, atleast for send/receive operations.


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

Large-Send-Offload ( LSO ) support added

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 ) ;

Collapse Copy Code
 /*** Initialize NDIS_OFFLOAD ****/
NdisZeroMemory( NdisOffload,
NdisOffload->Header.Type = NDIS_OBJECT_TYPE_OFFLOAD ;
NdisOffload->Header.Revision = NDIS_OFFLOAD_REVISION_1 ;
NdisOffload->Header.Size = sizeof(NDIS_OFFLOAD);
// Initialize the NDIS_TCP_LARGE_SEND_OFFLOAD_V1 structure
// embedded in NDIS_OFFLOAD 
LsoV1->IPv4.Encapsulation = NDIS_ENCAPSULATION_IEEE_802_3 ;
LsoV1->IPv4.MaxOffLoadSize = MP_MAX_TCP_OFFLOAD_SIZE ;
LsoV1->IPv4.MinSegmentCount = TCP_OFFLOAD_MIN_SEGMENTS ;
NdisZeroMemory (
OffloadAttributes.Header.Type =
OffloadAttributes.Header.Revision =
OffloadAttributes.Header.Size =
OffloadAttributes.HardwareOffloadCapabilities =
OffloadAttributes.DefaultOffloadConfiguration = NdisOffload ;
status = NdisMSetMiniportAttributes( Adapter->AdapterHandle,

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

Collapse Copy Code
// Verify the length
if (InformationBufferLength < sizeof(NDIS_OFFLOAD_ENCAPSULATION) )
Encap = (PNDIS_OFFLOAD_ENCAPSULATION)InformationBuffer ;
Adapter->NdisOffloadEncapSulation = Encap->IPv4.Enabled ;
if ( NDIS_OFFLOAD_SET_ON == Encap->IPv4.Enabled )
Encap->IPv4.EncapsulationType = NDIS_ENCAPSULATION_IEEE_802_3 ;
BytesRead = InformationBufferLength;
break ;

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

Collapse Copy 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
NBL->TcpPayLoad = TotalBytesInNBL - NBL->TcpHeaderOffset + TcpHeaderLength;

Here is the code

Collapse Copy Code
PeekTcpHeader ( pMpTcb->NetBufferList, pMpTcb->NetBuffer ) ;

Step 5

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

Collapse Copy Code
if ( bLSOenabled ) {
pHwTbd->status |= (LGSENbit | pNBLcontext->MSS) ;

Step 6

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

Collapse Copy Code

JUMBO frame support added

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

Collapse Copy Code
#define NIC_MAX_XMIT_FRAME_SIZE 7040 // multiple 0f 64

Power Managment Capabilities added

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

Collapse Copy Code
pPower_Management_Capabilities->Flags = NDIS_DEVICE_WAKE_UP_ENABLE ;
pPower_Management_Capabilities->WakeUpCapabilities.MinMagicPacketWakeUp = NdisDeviceStateD3;
pPower_Management_Capabilities->WakeUpCapabilities.MinPatternWakeUp = NdisDeviceStateUnspecified;
pPower_Management_Capabilities->WakeUpCapabilities.MinLinkChangeWakeUp = NdisDeviceStateUnspecified ;
*pulInfoLen = sizeof (*pPower_Management_Capabilities);

TEST : MAGIC packet WOL worked fine with this code

About Copyright

* 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.


Any form of comments and suggestions are welcome to this forum or to
remove underscore.
Cheers & good luck


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


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

posted on 2009-04-12 00:15 iniwf 阅读(1560) 评论(1)  编辑 收藏 引用 所属分类: 驱动


# re: NDIS sample - 6.0 miniport driver for realtek 8168/8169/8111/8110 2010-08-23 09:31 dress

These two small addons perform a simple web site search either in the google groups or on CP. Select a piece of text in the code editor, to pop up the menu and then select where to search for the selected text. That's all. The search results will be opened inside VS.NET.  回复  更多评论   

【推荐】超50万行VC++源码: 大型组态工控、电力仿真CAD与GIS源码库
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理