Horodatage des paquets
Introduction
De nombreuses cartes d’interface réseau (cartes réseau ou cartes réseau) peuvent générer un horodatage dans leur matériel chaque fois qu’un paquet est reçu ou transmis. L’horodatage est généré à l’aide de la propre horloge matérielle de la carte réseau. Cette fonctionnalité est utilisée en particulier par le protocole PTP (Precision Time Protocol), qui est un protocole de synchronisation de l’heure. PTP prévoit l’utilisation de ces horodatages matériels dans le protocole lui-même.
Les horodatages peuvent, par exemple, être utilisés pour calculer le temps passé par un paquet dans la pile réseau de la machine avant d’être envoyé ou reçu du réseau. Ces calculs peuvent ensuite être utilisés par PTP pour améliorer la précision de la synchronisation temporelle. La prise en charge de l’horodatage des paquets des cartes réseau est parfois conçue spécifiquement pour le protocole PTP. Dans d’autres cas, un support plus général est fourni.
Les API d’horodatage permettent à Windows de prendre en charge la fonctionnalité d’horodatage matériel des cartes réseau pour le protocole PTP version 2. Dans l’ensemble, les fonctionnalités incluent la possibilité de pilotes de cartes réseau pour prendre en charge les horodatages, et pour les applications en mode utilisateur de consommer des horodatages associés aux paquets via des sockets Windows (voir Timestamping Winsock). En outre, la possibilité de générer des horodatages logiciels est également disponible, ce qui permet à un pilote réseau de générer des horodatages dans les logiciels. Ces horodatages logiciels sont générés par les pilotes de carte réseau à l’aide de l’équivalent en mode noyau de QueryPerformanceCounter (QPC). Toutefois, l’activation des horodatages matériels et logiciels n’est pas prise en charge.
En particulier, les API d’horodatage de paquets de l’Assistance du protocole Internet (IP Helper) décrites dans cette rubrique permettent aux applications en mode utilisateur de déterminer la capacité d’horodatage d’une carte réseau et d’interroger les horodatages à partir de la carte réseau sous la forme d’horodatages croisés (décrits ci-dessous).
Prise en charge du protocole Precision Time Protocol version 2
Comme mentionné, l’objectif main de la prise en charge de l’horodatage dans Windows est de prendre en charge le protocole PTPv2 (Precision Time Protocol version 2). Dans PTPv2, tous les messages n’ont pas besoin d’un horodatage. En particulier, les messages d’événements PTP utilisent des horodatages. Actuellement, la prise en charge est limitée à PTPv2 sur UDP (User Datagram Protocol). PTP sur Ethernet brut n’est pas pris en charge.
L’horodatage est pris en charge pour le fonctionnement de PTPv2 en mode 2 étapes . L’étape 2 fait référence au mode dans lequel les horodatages réels dans les paquets PTP ne sont pas générés à la volée dans le matériel, mais sont plutôt récupérés à partir du matériel et transmis sous forme de messages distincts (par exemple, à l’aide d’un message de suivi).
En résumé, vous pouvez utiliser les API d’horodatage de paquets Ip Helper (Internet Protocol Helper), ainsi que la prise en charge de l’horodatage de Winsock, dans une application PTPv2 pour améliorer sa précision de synchronisation temporelle.
Récupération des fonctionnalités d’horodatage d’une carte réseau
Une application telle qu’un service de synchronisation de l’heure PTP doit déterminer la capacité d’horodatage d’une carte réseau. À l’aide des fonctionnalités récupérées, l’application peut ensuite décider si elle souhaite utiliser des horodatages.
Même si une carte réseau prend en charge les horodatages, il est nécessaire de conserver la fonctionnalité désactivée par défaut. Un adaptateur active l’horodatage lorsqu’il lui est demandé de le faire. Windows fournit des API permettant à une application de récupérer les fonctionnalités du matériel, ainsi que les fonctionnalités activées.
Pour récupérer les fonctionnalités d’horodatage prises en charge d’une carte réseau, vous appelez la fonction GetInterfaceSupportedTimestampCapabilities , en fournissant l’identificateur local unique (LUID) de la carte réseau, puis en récupérant les fonctionnalités d’horodatage prises en charge sous la forme d’un objet INTERFACE_TIMESTAMP_CAPABILITIES .
Le code retourné par GetInterfaceSupportedTimestampCapabilities indique si l’appel a réussi ou non et si une valeur de INTERFACE_TIMESTAMP_CAPABILITIES renseignée a été récupérée ou non.
Pour récupérer les fonctionnalités d’horodatage actuellement activées d’une carte réseau, vous appelez la fonction GetInterfaceActiveTimestampCapabilities , en fournissant l’identificateur unique local (LUID) de la carte réseau et en retour récupérant les fonctionnalités d’horodatage activées sous la forme d’un objet INTERFACE_TIMESTAMP_CAPABILITIES .
Là encore, le code retourné par GetInterfaceActiveTimestampCapabilities indique la réussite ou l’échec, et indique si une valeur de INTERFACE_TIMESTAMP_CAPABILITIES valide a été récupérée ou non.
Les cartes réseau peuvent prendre en charge diverses fonctionnalités d’horodatage. Par exemple, certains adaptateurs peuvent horodatage de chaque paquet lors de l’envoi et de la réception, tandis que d’autres prennent uniquement en charge les paquets PTPv2. La structure INTERFACE_TIMESTAMP_CAPABILITIES décrit les fonctionnalités exactes prises en charge par une carte réseau.
Récupération des horodatages croisés à partir d’une carte réseau
Lorsque vous utilisez des horodatages matériels, une application PTP doit établir une relation (par exemple, en utilisant des techniques mathématiques appropriées) entre l’horloge matérielle de la carte réseau et une horloge système. Cela est nécessaire pour qu’une valeur représentant une heure dans une unité d’horloge puisse être convertie en une autre unité d’horloge. Les horodatages croisés sont fournis à cet effet, et votre application peut échantillonner régulièrement des horodatages croisés afin d’établir une telle relation.
Pour ce faire, appelez la fonction CaptureInterfaceHardwareCrossTimestamp , en fournissant l’identificateur local unique (LUID) de la carte réseau, puis en récupérant l’horodatage de la carte réseau sous la forme d’un objet INTERFACE_HARDWARE_CROSSTIMESTAMP .
Notifications de modification de capacité d’horodatage
Pour être averti si les fonctionnalités d’horodatage d’une carte réseau changent, appelez la fonction RegisterInterfaceTimestampConfigChange , en fournissant un pointeur vers la fonction de rappel que vous avez implémentée, ainsi qu’un contexte facultatif alloué à l’appelant.
RegisterInterfaceTimestampConfigChange retourne un handle que vous pouvez ensuite passer à UnregisterInterfaceTimestampConfigChange afin d’annuler l’inscription de votre fonction de rappel.
Exemple de code 1 : récupération des fonctionnalités d’horodatage et des horodatages croisés
// main.cpp in a Console App project.
#include <stdio.h>
#include <winsock2.h>
#include <iphlpapi.h>
#pragma comment(lib, "Iphlpapi")
BOOL
IsPTPv2HardwareTimestampingSupportedForIPv4(PINTERFACE_TIMESTAMP_CAPABILITIES timestampCapabilities)
{
// Supported if both receive and transmit side support is present
if (((timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv4EventMessageReceive) ||
(timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv4AllMessageReceive) ||
(timestampCapabilities->HardwareCapabilities.AllReceive))
&&
((timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv4EventMessageTransmit) ||
(timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv4AllMessageTransmit) ||
(timestampCapabilities->HardwareCapabilities.TaggedTransmit) ||
(timestampCapabilities->HardwareCapabilities.AllTransmit)))
{
return TRUE;
}
return FALSE;
}
BOOL
IsPTPv2HardwareTimestampingSupportedForIPv6(PINTERFACE_TIMESTAMP_CAPABILITIES timestampCapabilities)
{
// Supported if both receive and transmit side support is present
if (((timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv6EventMessageReceive) ||
(timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv6AllMessageReceive) ||
(timestampCapabilities->HardwareCapabilities.AllReceive))
&&
((timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv6EventMessageTransmit) ||
(timestampCapabilities->HardwareCapabilities.PtpV2OverUdpIPv6AllMessageTransmit) ||
(timestampCapabilities->HardwareCapabilities.TaggedTransmit) ||
(timestampCapabilities->HardwareCapabilities.AllTransmit)))
{
return TRUE;
}
return FALSE;
}
enum SupportedTimestampType
{
TimestampTypeNone = 0,
TimestampTypeSoftware = 1,
TimestampTypeHardware = 2
};
// This function checks and returns the supported timestamp capabilities for an interface for
// a PTPv2 application
SupportedTimestampType
CheckActiveTimestampCapabilitiesForPtpv2(NET_LUID interfaceLuid)
{
DWORD result = NO_ERROR;
INTERFACE_TIMESTAMP_CAPABILITIES timestampCapabilities;
SupportedTimestampType supportedType = TimestampTypeNone;
result = GetInterfaceActiveTimestampCapabilities(
&interfaceLuid,
×tampCapabilities);
if (result != NO_ERROR)
{
printf("Error retrieving hardware timestamp capabilities: %d\n", result);
goto Exit;
}
if (IsPTPv2HardwareTimestampingSupportedForIPv4(×tampCapabilities) &&
IsPTPv2HardwareTimestampingSupportedForIPv6(×tampCapabilities))
{
supportedType = TimestampTypeHardware;
goto Exit;
}
else
{
if ((timestampCapabilities.SoftwareCapabilities.AllReceive) &&
((timestampCapabilities.SoftwareCapabilities.AllTransmit) ||
(timestampCapabilities.SoftwareCapabilities.TaggedTransmit)))
{
supportedType = TimestampTypeSoftware;
}
}
Exit:
return supportedType;
}
// Helper function which does the correlation between hardware and system clock
// using mathematical techniques
void ComputeCorrelationOfHardwareAndSystemTimestamps(INTERFACE_HARDWARE_CROSSTIMESTAMP *crossTimestamp);
// An application would call this function periodically to gather a set
// of matching timestamps for use in converting hardware timestamps to
// system timestamps
DWORD
RetrieveAndProcessCrossTimestamp(NET_LUID interfaceLuid)
{
DWORD result = NO_ERROR;
INTERFACE_HARDWARE_CROSSTIMESTAMP crossTimestamp;
result = CaptureInterfaceHardwareCrossTimestamp(
&interfaceLuid,
&crossTimestamp);
if (result != NO_ERROR)
{
printf("Error retrieving cross timestamp for the interface: %d\n", result);
goto Exit;
}
// Process crossTimestamp further to create a relation between the hardware clock
// of the NIC and the QPC values using appropriate mathematical techniques
ComputeCorrelationOfHardwareAndSystemTimestamps(&crossTimestamp);
Exit:
return result;
}
int main()
{
}
Exemple de code 2 : inscription aux notifications de modification de capacité d’horodatage
Cet exemple montre comment votre application peut utiliser les horodatages de bout en bout.
// main.cpp in a Console App project.
#include <stdlib.h>
#include <stdio.h>
#include <winsock2.h>
#include <mswsock.h>
#include <iphlpapi.h>
#include <mstcpip.h>
#pragma comment(lib, "Ws2_32")
#pragma comment(lib, "Iphlpapi")
// Globals and function declarations used by the application.
// The sample functions and skeletons demonstrate:
// - Checking timestamp configuration for an interface to determine if timestamping can be used
// - If timestamping is enabled, starts tracking changes in timestamp configuration
// - Performing correlation between hardware and system timestamps using cross timestamps
// on a separate thread depending on the timestamp type configured
// - Receiving a packet and computing the latency between when the timestamp
// was generated on packet reception, and when the packet was received by
// the application through the socket
// The sample tries to demonstrate how an application could use timestamps. It is not thread safe
// and does not do exhaustive error checking.
// Lot of the functions are provided as skeletons, or only declared and invoked
// but are not defined. It is up to
// the application to implement these suitably.
// An application could use the functions below by e.g.
// - Call InitializeTimestampingForInterface for the interface it wants to track for timestamping capability.
// - Call EstimateReceiveLatency to estimate the receive latency of a packet depending on the timestamp
// type configured for the interface.
enum SupportedTimestampType
{
TimestampTypeNone = 0,
TimestampTypeSoftware = 1,
TimestampTypeHardware = 2
};
// interfaceBeingTracked is the interface the PTPv2 application
// intends to use for timestamping purpose.
wchar_t* interfaceBeingTracked;
// The active timestamping type determined for
// interfaceBeingTracked.
SupportedTimestampType timestampTypeEnabledForInterface;
HANDLE correlationThread;
HANDLE threadStopEvent;
HIFTIMESTAMPCHANGE TimestampChangeNotificationHandle = NULL;
// Function from sample above to check if an interface supports timestamping for PTPv2.
SupportedTimestampType CheckActiveTimestampCapabilitiesForPtpv2(NET_LUID interfaceLuid);
// Function from sample above to retrieve cross timestamps and process them further.
DWORD RetrieveAndProcessCrossTimestamp(NET_LUID interfaceLuid);
// Helper function which registers for timestamp configuration changes.
DWORD RegisterTimestampChangeNotifications();
// Callback function which is invoked when timestamp configuration changes
// for some network interface.
INTERFACE_TIMESTAMP_CONFIG_CHANGE_CALLBACK TimestampConfigChangeCallback;
// Function which does the correlation between hardware and system clock
// using mathematical techniques. It is periodically invoked and provided
// a sample of cross timestamp to compute a correlation.
void ComputeCorrelationOfHardwareAndSystemTimestamps(INTERFACE_HARDWARE_CROSSTIMESTAMP *crossTimestamp);
// Helper function which converts a hardware timestamp from the NIC clock
// to system timestamp (QPC) values. It is assumed that this works together
// with the ComputeCorrelationOfHardwareAndSystemTimestamps function
// to derive the correlation.
ULONG64 ConvertHardwareTimestampToQpc(ULONG64 HardwareTimestamp);
// Start function of thread which periodically samples
// cross timestamps to correlate hardware and software timestamps.
DWORD WINAPI CorrelateHardwareAndSystemTimestamps(LPVOID);
// Helper function which starts a new thread at CorrelateHardwareAndSystemTimestamps.
DWORD StartCorrelatingHardwareAndSytemTimestamps();
// Helper function which restarts correlation when some change is detected.
DWORD RestartCorrelatingHardwareAndSystemTimestamps();
// Stops the correlation thread.
DWORD StopCorrelatingHardwareAndSystemTimestamps();
DWORD
FindInterfaceFromFriendlyName(wchar_t* friendlyName, NET_LUID* interfaceLuid)
{
DWORD result = 0;
ULONG flags = 0;
ULONG outBufLen = 0;
PIP_ADAPTER_ADDRESSES pAddresses = NULL;
PIP_ADAPTER_ADDRESSES currentAddresses = NULL;
result = GetAdaptersAddresses(0,
flags,
NULL,
pAddresses,
&outBufLen);
if (result == ERROR_BUFFER_OVERFLOW)
{
pAddresses = (PIP_ADAPTER_ADDRESSES)malloc(outBufLen);
result = GetAdaptersAddresses(0,
flags,
NULL,
pAddresses,
&outBufLen);
if (result != NO_ERROR)
{
goto Done;
}
}
else if (result != NO_ERROR)
{
goto Done;
}
currentAddresses = pAddresses;
while (currentAddresses != NULL)
{
if (wcscmp(friendlyName, currentAddresses->FriendlyName) == 0)
{
result = ConvertInterfaceIndexToLuid(currentAddresses->IfIndex, interfaceLuid);
goto Done;
}
currentAddresses = currentAddresses->Next;
}
result = ERROR_NOT_FOUND;
Done:
if (pAddresses != NULL)
{
free(pAddresses);
}
return result;
}
// This function checks if an interface is suitable for
// timestamping for PTPv2. If so, it registers for timestamp
// configuration changes and initializes some globals.
// If hardware timestamping is enabled it also starts
// correlation thread.
DWORD
InitializeTimestampingForInterface(wchar_t* friendlyName)
{
DWORD error;
SupportedTimestampType supportedType = TimestampTypeNone;
NET_LUID interfaceLuid;
error = FindInterfaceFromFriendlyName(friendlyName, &interfaceLuid);
if (error != 0)
{
return error;
}
supportedType = CheckActiveTimestampCapabilitiesForPtpv2(interfaceLuid);
if (supportedType != TimestampTypeNone)
{
error = RegisterTimestampChangeNotifications();
if (error != NO_ERROR)
{
return error;
}
if (supportedType == TimestampTypeHardware)
{
threadStopEvent = CreateEvent(
NULL,
FALSE,
FALSE,
NULL
);
if (threadStopEvent == NULL)
{
return GetLastError();
}
error = StartCorrelatingHardwareAndSytemTimestamps();
if (error != 0)
{
return error;
}
}
interfaceBeingTracked = friendlyName;
timestampTypeEnabledForInterface = supportedType;
return error;
}
return ERROR_NOT_SUPPORTED;
}
DWORD
RegisterTimestampChangeNotifications()
{
DWORD retcode = NO_ERROR;
// Register with NULL context
retcode = RegisterInterfaceTimestampConfigChange(TimestampConfigChangeCallback, NULL, &TimestampChangeNotificationHandle);
if (retcode != NO_ERROR)
{
printf("Error when calling RegisterIfTimestampConfigChange %d\n", retcode);
}
return retcode;
}
// The callback invoked when change in some interface’s timestamping configuration
// happens. The callback takes appropriate action based on the new capability of the
// interface. The callback assumes that there is only 1 NIC. If multiple NICs are being
// tracked for timestamping then the application would need to check all of them.
VOID
WINAPI
TimestampConfigChangeCallback(
_In_ PVOID /*CallerContext*/
)
{
SupportedTimestampType supportedType;
NET_LUID interfaceLuid;
DWORD error;
error = FindInterfaceFromFriendlyName(interfaceBeingTracked, &interfaceLuid);
if (error != NO_ERROR)
{
if (timestampTypeEnabledForInterface == TimestampTypeHardware)
{
StopCorrelatingHardwareAndSystemTimestamps();
timestampTypeEnabledForInterface = TimestampTypeNone;
}
return;
}
supportedType = CheckActiveTimestampCapabilitiesForPtpv2(interfaceLuid);
if ((supportedType == TimestampTypeHardware) &&
(timestampTypeEnabledForInterface == TimestampTypeHardware))
{
// NIC could have been restarted, restart the correlation between hardware and
// system timestamps.
RestartCorrelatingHardwareAndSystemTimestamps();
}
else if (supportedType == TimestampTypeHardware)
{
// Start thread correlating hardware and software timestamps
StartCorrelatingHardwareAndSytemTimestamps();
}
else if (supportedType != TimestampTypeHardware)
{
// Hardware timestamps are not enabled, stop correlation
StopCorrelatingHardwareAndSystemTimestamps();
}
timestampTypeEnabledForInterface = supportedType;
}
DWORD
StartCorrelatingHardwareAndSytemTimestamps()
{
// Create a new thread which starts at CorrelateHardwareAndSoftwareTimestamps
correlationThread = CreateThread(
NULL,
0,
CorrelateHardwareAndSystemTimestamps,
NULL,
0,
NULL);
if (correlationThread == NULL)
{
return GetLastError();
}
}
// Thread which periodically invokes functions to
// sample cross timestamps and use them to compute
// correlation between hardware and system timestamps.
DWORD WINAPI
CorrelateHardwareAndSystemTimestamps(LPVOID /*lpParameter*/)
{
DWORD error;
NET_LUID interfaceLuid;
DWORD result;
result = FindInterfaceFromFriendlyName(interfaceBeingTracked, &interfaceLuid);
if (result != 0)
{
return result;
}
while (TRUE)
{
error = RetrieveAndProcessCrossTimestamp(interfaceLuid);
// Sleep and repeat till the thread gets a signal to stop
result = WaitForSingleObject(threadStopEvent, 5000);
if (result != WAIT_TIMEOUT)
{
if (result == WAIT_OBJECT_0)
{
return 0;
}
else if (result == WAIT_FAILED)
{
return GetLastError();
}
return result;
}
}
}
DWORD
StopCorrelatingHardwareAndSystemTimestamps()
{
SetEvent(threadStopEvent);
return 0;
}
// Function which receives a packet and estimates the latency between the
// point at which receive timestamp (of appropriate type) was generated
// and when the packet was received in the app through the socket.
// The sample assumes that there is only 1 NIC in the system. This is the NIC which is tracked through
// interfaceBeingTracked for correlation purpose, and through which packets are being
// received by the socket.
// The recvmsg parameter is of type LPFN_WSARECVMSG and an application can
// retrieve it by issuing WSAIoctl
// with SIO_GET_EXTENSION_FUNCTION_POINTER control
// and WSAID_WSARECVMSG. Please refer to msdn.
void EstimateReceiveLatency(SOCKET sock, LPFN_WSARECVMSG recvmsg)
{
DWORD numBytes;
INT error;
CHAR data[512];
CHAR control[WSA_CMSG_SPACE(sizeof(UINT64))] = { 0 };
WSABUF dataBuf;
WSABUF controlBuf;
WSAMSG wsaMsg;
UINT64 socketTimestamp = 0;
ULONG64 appLevelTimestamp;
ULONG64 packetReceivedTimestamp;
dataBuf.buf = data;
dataBuf.len = sizeof(data);
controlBuf.buf = control;
controlBuf.len = sizeof(control);
wsaMsg.name = NULL;
wsaMsg.namelen = 0;
wsaMsg.lpBuffers = &dataBuf;
wsaMsg.dwBufferCount = 1;
wsaMsg.Control = controlBuf;
wsaMsg.dwFlags = 0;
// Configure rx timestamp reception.
TIMESTAMPING_CONFIG config = { 0 };
config.Flags |= TIMESTAMPING_FLAG_RX;
error =
WSAIoctl(
sock,
SIO_TIMESTAMPING,
&config,
sizeof(config),
NULL,
0,
&numBytes,
NULL,
NULL);
if (error == SOCKET_ERROR)
{
printf("WSAIoctl failed %d\n", WSAGetLastError());
return;
}
error =
recvmsg(
sock,
&wsaMsg,
&numBytes,
NULL,
NULL);
if (error == SOCKET_ERROR)
{
printf("recvmsg failed %d\n", WSAGetLastError());
return;
}
if (timestampTypeEnabledForInterface != TimestampTypeNone)
{
// Capture system timestamp (QPC) upon message reception.
LARGE_INTEGER t1;
QueryPerformanceCounter(&t1);
appLevelTimestamp = t1.QuadPart;
printf("received packet\n");
// Look for socket rx timestamp returned via control message.
BOOLEAN retrievedTimestamp = FALSE;
PCMSGHDR cmsg = WSA_CMSG_FIRSTHDR(&wsaMsg);
while (cmsg != NULL)
{
if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SO_TIMESTAMP)
{
socketTimestamp = *(PUINT64)WSA_CMSG_DATA(cmsg);
retrievedTimestamp = TRUE;
break;
}
cmsg = WSA_CMSG_NXTHDR(&wsaMsg, cmsg);
}
if (retrievedTimestamp)
{
// Compute socket receive path latency.
LARGE_INTEGER clockFrequency;
ULONG64 elapsedMicroseconds;
if (timestampTypeEnabledForInterface == TimestampTypeHardware)
{
packetReceivedTimestamp = ConvertHardwareTimestampToQpc(socketTimestamp);
}
else
{
packetReceivedTimestamp = socketTimestamp;
}
QueryPerformanceFrequency(&clockFrequency);
// Compute socket receive path latency.
elapsedMicroseconds = appLevelTimestamp - packetReceivedTimestamp;
elapsedMicroseconds *= 1000000;
elapsedMicroseconds /= clockFrequency.QuadPart;
printf("RX latency estimation: %lld microseconds\n",
elapsedMicroseconds);
}
else
{
printf("failed to retrieve RX timestamp\n");
}
}
}
int main()
{
}
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour