Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Layer Build and Validation for DoIP (Diagnostic over IP) Support #1655

Open
wants to merge 22 commits into
base: dev
Choose a base branch
from

Conversation

raissi-oussema
Copy link

@raissi-oussema raissi-oussema commented Dec 7, 2024

DoIP Protocol Overview

The Diagnostic over IP (DoIP) protocol is used in automotive diagnostic systems to facilitate communication between diagnostic tools and ECUs (Electronic Control Units) over IP-based networks. It enables remote diagnostics, configuration, and software updates over Ethernet, offering an efficient and scalable solution for modern vehicles.

Header Structure (8 bytes)

protocol version (1 byte)
invert protocol version (1 byte)
payload type (2 bytes)
payload length (4 bytes)

Pyload types / code / structure

  • "Generic DOIP header Nack" (0x0000) (header + nackCode (1 byte : required))
  • "Vehicle identification request" (0x0001) (header)
  • "Vehicle identification request with EID" (0x0002) (header + EID (6 bytes : required))
  • "Vehicle identification request with VIN" (0x0003) (header + VIN (17 bytes : required))
  • "Vehicle announcement message" (0x0004) (header + VIN (17 bytes : required) + logical address (2bytes : required) + EID (6 bytes : required) + GID (6 bytes : required) + further action (1 bytes : required)+ sync status (1 bytes : optional)).
  • "Routing activation request" (0x0005) (header + source address (2 bytes : required) + activation type (1 byte:required) + reservedISO (4 bytes : required) + reservedOEM (4 bytes : optional)).
  • "Routing activation response" (0x0006) (header + tester adress(2 bytes : required) + response code (1 byte:required) + reservedISO (4 bytes : required) + reservedOEM (4 bytes : optional)).
  • "Alive check request" (0x0007) (header)
  • "Alive check response" (0x0008) (header + source address (2 byte : required))
  • "DOIP entity status request" (0x4001) (header)
  • "DOIP entity status response" (0x4002) (header + node type (1 byte : required) + max concurrent socket (1 byte : required) + currently opened sockets (1 byte : required) + max data size(4 bytes : optional))
  • "Diagnostic power mode request information" (0x4003) (header)
  • "Diagnostic power mode response information" (0x4004) (header + power mode (1 byte : required))
  • "Diagnostic message" (0x8001) (header + source address (2 bytes : required) + target address (2 bytes : required) + UDS message (n bytes : required ; n > 1))
  • "Diagnostic message Ack" (0x8002) (header + source address (2 bytes : required) + target address (2 bytes : required) + ack code (1 byte : required)) + previous message (n bytes : optional ; n>0))
  • "Diagnostic message Nack" (0x8003) (header + source address (2 bytes : required) + target address (2 bytes : required) + Nack code (1 byte : required)) + previous message (n bytes : optional ; n>0))

@Dimi1010
Copy link
Collaborator

Dimi1010 commented Dec 8, 2024

As per the contributing guidelines, please retarget the PR to the dev branch instead of the master.

@tigercosmos tigercosmos changed the base branch from master to dev December 8, 2024 09:37
@egecetin egecetin closed this Dec 8, 2024
@egecetin egecetin reopened this Dec 8, 2024
@egecetin egecetin linked an issue Dec 8, 2024 that may be closed by this pull request
@raissi-oussema
Copy link
Author

Observed several issues in the CI pipelines, likely due to missing definitions for htobe16 and other endianness conversion macros. All tests and pre-commit checks are passed in my linux machine.
Adding an import for "EndianPortable.h" in last PR is expected to resolve these problems.

Comment on lines 250 to 253
/**
* Diagnostic over IP protocol (DOIP)
*/
const ProtocolType DOIP = 38;
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ID 38 is already taken by DHCPv6 protocol. The next available ID is 58, please add it after GTPv2

@@ -437,7 +437,6 @@ namespace pcpp

HttpResponseStatusCode() = default;

// cppcheck-suppress noExplicitConstructor
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why removing this cppcheck-suppress comment?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cppcheck flags this as an incorrect suppression on my local machine. Let me know if you think I should revert it.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is interesting. Which version of CPPcheck are you using?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2.7 as recommanded in CONTRIBUTING.md and still flags incorrect suppression, I'm keeping this changes so can I commit my recents updates,

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why update this file?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same thing as my previous comment, I only removed some suppress-checks detected as incorrect

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add one pcap file with all of these packets?

Copy link
Author

@raissi-oussema raissi-oussema Dec 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes sure, I'll revert suppress-checks and add pcap file containig all tested packets in next PR, also try to cover some missing checks based on codecov feedback

Copy link

codecov bot commented Dec 10, 2024

Codecov Report

Attention: Patch coverage is 94.14414% with 104 lines in your changes missing coverage. Please review.

Project coverage is 83.53%. Comparing base (d60c699) to head (929287b).

Files with missing lines Patch % Lines
Packet++/src/DoIpLayerData.cpp 89.01% 53 Missing and 15 partials ⚠️
Packet++/src/DoIpLayer.cpp 88.52% 9 Missing and 12 partials ⚠️
Tests/Packet++Test/Tests/DoIpTests.cpp 98.62% 0 Missing and 12 partials ⚠️
Packet++/header/DoIpLayerData.h 76.92% 0 Missing and 3 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##              dev    #1655      +/-   ##
==========================================
+ Coverage   83.11%   83.53%   +0.41%     
==========================================
  Files         277      283       +6     
  Lines       48207    50037    +1830     
  Branches    10192    10470     +278     
==========================================
+ Hits        40069    41796    +1727     
- Misses       7243     7301      +58     
- Partials      895      940      +45     
Flag Coverage Δ
alpine320 75.31% <81.45%> (+0.20%) ⬆️
fedora40 75.35% <82.05%> (+0.19%) ⬆️
macos-13 80.92% <88.87%> (+0.30%) ⬆️
macos-14 80.92% <88.87%> (+0.30%) ⬆️
macos-15 80.85% <88.21%> (+0.26%) ⬆️
mingw32 70.51% <61.43%> (-0.35%) ⬇️
mingw64 70.46% <61.50%> (-0.37%) ⬇️
npcap 85.21% <86.54%> (-0.05%) ⬇️
rhel94 75.20% <81.99%> (+0.21%) ⬆️
ubuntu2004 58.33% <53.08%> (-0.26%) ⬇️
ubuntu2004-zstd 58.47% <53.08%> (-0.21%) ⬇️
ubuntu2204 75.12% <81.97%> (+0.22%) ⬆️
ubuntu2204-icpx 61.27% <55.83%> (-0.18%) ⬇️
ubuntu2404 75.36% <81.45%> (+0.20%) ⬆️
unittest 83.53% <94.14%> (+0.41%) ⬆️
windows-2019 85.31% <86.44%> (+0.02%) ⬆️
windows-2022 85.34% <86.54%> (+0.02%) ⬆️
winpcap 85.30% <86.54%> (+0.04%) ⬆️
xdp 51.52% <81.97%> (+0.98%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@seladb
Copy link
Owner

seladb commented Jan 3, 2025

@raissi-oussema are you planning to continue working on this PR?

@raissi-oussema
Copy link
Author

Hi, I was engaged with other tasks, but I plan to get back to this PR soon. Thanks for your understanding!

raissi-oussema and others added 2 commits January 6, 2025 01:52
.improve  maps searchs for doipEnumsToStrings
.cover more uses cases based on codecov feedback
@raissi-oussema
Copy link
Author

Design suggestions or code improvements are always welcome and greatly appreciated.

@seladb
Copy link
Owner

seladb commented Jan 8, 2025

@raissi-oussema to make it easier to review, do you think you can add some documentation on the DoIP protocol to the PR body?

It'd mostly be helpful to get more details on the header structure and different possible message

@raissi-oussema
Copy link
Author

@seladb I need support for CI pipelines, I can't figure out why are they still failing. And a clear documentation was successfully added to PR body to make it easier for you to start the code review.

@Dimi1010
Copy link
Collaborator

Dimi1010 commented Jan 12, 2025

@seladb I need support for CI pipelines, I can't figure out why are they still failing. And a clear documentation was successfully added to PR body to make it easier for you to start the code review.

Doxigen pipeline:
/__w/PcapPlusPlus/PcapPlusPlus/Packet++/header/DoIpLayer.h:42: error: Compound pcpp::DoIpLayer is not documented. (warning treated as error, aborting now)

XDP pipeline:
That is an issue with the CI image. Merge latest changes from dev branch and it should be fine.

VS pipeline:
Tbh, no idea om that one. It seems the opencoverage download link stopped working for a bit or something.

@raissi-oussema
Copy link
Author

@seladb I need support for CI pipelines, I can't figure out why are they still failing. And a clear documentation was successfully added to PR body to make it easier for you to start the code review.

Doxigen pipeline: /__w/PcapPlusPlus/PcapPlusPlus/Packet++/header/DoIpLayer.h:42: error: Compound pcpp::DoIpLayer is not documented. (warning treated as error, aborting now)

XDP pipeline: That is an issue with the CI image. Merge latest changes from dev branch and it should be fine.

VS pipeline: Tbh, no idea om that one. It seems the opencoverage download link stopped working for a bit or something.

What could be the problem for dioxygen pipeline, doipLayer.h is well documented [line 42] ?

Packet++/header/DoIpLayer.h Outdated Show resolved Hide resolved
Packet++/header/DoIpLayer.h Outdated Show resolved Hide resolved
Packet++/header/DoIpLayer.h Outdated Show resolved Hide resolved
Packet++/src/DoIpLayer.cpp Outdated Show resolved Hide resolved
Packet++/src/DoIpLayer.cpp Outdated Show resolved Hide resolved
Packet++/src/DoIpLayer.cpp Outdated Show resolved Hide resolved
Packet++/src/DoIpLayer.cpp Outdated Show resolved Hide resolved
Packet++/header/DoIpLayerData.h Outdated Show resolved Hide resolved
Packet++/header/DoIpLayerData.h Show resolved Hide resolved
// implement abstract methods

/**
* TODO, parse UDS layer
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this for another PR? If so, should the remaining data be parsed as a generic payload layer for now?

Copy link
Author

@raissi-oussema raissi-oussema Jan 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

m_NextLayer is intended to be the UDS layer, which has not been implemented yet. In the future, as more knowledge is gained, either I or another contributor may add this functionality. For now, I suggest parsing it as a generic layer, as you mentioned.
PS: the nextLayer will be parsed only when the payloadType is 0x8001.

Copy link
Author

@raissi-oussema raissi-oussema Jan 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

your feedback is highly appertiated, what do you think about adding this snippet of code:

void  parseNextLayer() override
		{
			if (getPayloadType() == DoIpPayloadTypes::DIAGNOSTIC_MESSAGE_TYPE)
			{
				size_t headerLen = sizeof(doiphdr);

				if (m_DataLen <= headerLen + 2 /*source address size*/ + 2 /*target address size*/)
					return;

				uint8_t* payload = m_Data + (headerLen + 2 + 2);
				size_t payloadLen = m_DataLen - (headerLen + 2 + 2);
				m_NextLayer = new PayloadLayer(payload, payloadLen, this, m_Packet);
				return;
			}
		}`

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

your feedback is highly appertiated, what do you think about adding this snippet of code:

void  parseNextLayer() override
		{
			if (getPayloadType() == DoIpPayloadTypes::DIAGNOSTIC_MESSAGE_TYPE)
			{
				size_t headerLen = sizeof(doiphdr);

				if (m_DataLen <= headerLen + 2 /*source address size*/ + 2 /*target address size*/)
					return;

				uint8_t* payload = m_Data + (headerLen + 2 + 2);
				size_t payloadLen = m_DataLen - (headerLen + 2 + 2);
				m_NextLayer = new PayloadLayer(payload, payloadLen, this, m_Packet);
				return;
			}
		}`

Seems good. Can the source address and target address used in that type of message be accessed from this layer? Since we are excluding it from the generic payload.

A minor tip, having headerLen be marked as constexpr might allow some compiler optimizations (such as the arithmetic using it + a literal being computed during compilation and hardcoded if possible).

Also why the return statement that is at the end of the block anyway?

Copy link
Author

@raissi-oussema raissi-oussema Jan 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Dimi1010 , this approach appears both safer and cleaner. It allows us to construct a DiagnosticMessage directly from the current layer, providing direct access to the diagnostic data. Using this data, we can then build a generic PayloadLayer.

void parseNextLayer() override
{
	DiagnosticMessageData diagnosticMessage;

	if (diagnosticMessage.buildFromLayer(this))
	{
		m_NextLayer = new PayloadLayer(diagnosticMessage.diagnosticData.data(),
				                             diagnosticMessage.diagnosticData.size(), this, m_Packet);
	}
}

buildFromLayer safely parses the current layer and verifies whether it represents a valid diagnostic message.
what do you think ?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but my question stands. DiagnosticMessageData has two other members (sourceAddress and targetAddress) which at the moment I don't see how the user can access them easily. They have neither accessors in the current DoIPLayer or are included as part of the UDSLayer (currently PayloadLayer).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sourceAddress and targetAddress are public members of DiagnosticMessageData class just like diagnosticData and they are not part of the UDS layer:

uint16_t sourceAddress;              /**< Source address of the message. */
uint16_t targetAddress;              /**< Target address for the diagnostic message. */
std::vector<uint8_t> diagnosticData; /**< Diagnostic message data with dynamic length. */

the user can access these fields by the method buildFromLayer .
I've made this dummy function just to show how to access to these fields :

void DoIpLayer::resolveDiagMessageFields()
	{
		DiagnosticMessageData diagnosticMessage;
		if (diagnosticMessage.buildFromLayer(this))
		{
			uint16_t srcAddr = diagnosticMessage.sourceAddress;
			uint16_t targetAddr = diagnosticMessage.targetAddress;
			std::vector<uint8_t> diagData = diagnosticMessage.diagnosticData;
		}
	}

Do you think this implementation need more improvement ?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, if i am understanding correctly the sequence is this?

  1. User somehow receives a DoIPLayer from a Packet
  2. User checks the payload type (via DoIPLayer::getPayloadType())
  3. Depending on the payload type user uses T::buildFromLayer(DoIPLayer) (T being the corresponding message struct) to populate the data from the layer into the struct.

Am I understanding the flow correctly?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes you are absolutely correct.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, that works fine. 👍

Packet++/header/DoIpLayer.h Show resolved Hide resolved
Packet++/header/DoIpLayerData.h Outdated Show resolved Hide resolved
Packet++/src/DoIpLayerData.cpp Outdated Show resolved Hide resolved
Packet++/src/DoIpLayerData.cpp Outdated Show resolved Hide resolved
// implement abstract methods

/**
* TODO, parse UDS layer
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, but my question stands. DiagnosticMessageData has two other members (sourceAddress and targetAddress) which at the moment I don't see how the user can access them easily. They have neither accessors in the current DoIPLayer or are included as part of the UDSLayer (currently PayloadLayer).

… as generic PayloadLayeruse byte shifting instead of reinterprete_cast for field crafting
@raissi-oussema raissi-oussema requested a review from seladb January 18, 2025 23:08
@raissi-oussema
Copy link
Author

@Dimi1010 Any additional feedback regarding design logic or code implementation is highly appreciated.

Copy link
Collaborator

@Dimi1010 Dimi1010 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a comment on the enum to string mappings. Everything else seems fine to me. It is just that and making the doxygen CI happy.

Copy link
Collaborator

@Dimi1010 Dimi1010 Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, it would be better to have the enum to string maps be converted to functions with switch statements. It would allow to expose a cleaner and uniform public API (toString(EnumType value) or toDescriptionString(EnumType value)) for the different enums. I also ran a benchmark and it does end up slightly faster (at least for DoIpProtocolVersion) due to some compilers producing a jump table (GCC and Clang do, MSVC doesn't).

The functions can then be folded into DoIpEnums.h with the implementations into DoIpEnums.cpp.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your feedback, @Dimi1010

In my humble opinion, unordered_map looks much cleaner and more declarative compared to switch statements, which can sometimes feel cluttered with redundant return or break statements. I’ve also ensured that edge cases, like missing keys, are handled appropriately whenever I use these maps.

To be honest, I haven’t focused much on the potential performance impact, as I believe the effect with these small enums would be negligible, though I understand it might require additional effort.

That said, if the difference in performance isn’t significant, I think we can keep it as it is. However, if you strongly feel this change is necessary, I’ll plan to prepare a fix over the weekend.

Thank you for your understanding!

Copy link
Collaborator

@Dimi1010 Dimi1010 Jan 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. Not necessarily a strong opinion on the switches. They can stay declared as maps.

Something else that occurred to me. The maps are declared as static in this header. For a global variable to be declared static that mean that is has internal linkage in the translation unit. For a header that means that each translation unit that header is included in, gets its own enum to string map. This is an issue as it leads duplicated maps in the different translation units. Please remove the static keyword from the maps.

Additionally, Are the maps supposed to be part of the public API or to be used only through the methods in DoIpLayerData?

  • If they aren't supposed to be part of the public API, please put them in the pcpp::internal namespace.
  • If they are to be part of the public API, I think that maybe having a function encapsulate the search/conversion would be better, even if the conversion is done with maps, as it detaches the implementation details of the conversion from the public API. What do you think?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Dimi1010 , thank you for your feedback!
Once again, your remarks are clear and insightful. The EnumToStringMaps are designed to be included only in DoIpLayerData, which avoids duplicate data in this context. However, for future designs, if anyone tries to use it in another translation unit, it could lead to increased memory consumption. I’ll definitely remove the static keyword as you suggested.
For the second question, yes, these maps are specific to the DoIP context, so they aren’t intended to be part of the public API. I’ll move them to the pcpp::internal namespace for better clarity and data organization.

Copy link
Collaborator

@Dimi1010 Dimi1010 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

support of doip (diagnostic over IP protocol)
5 participants