osnetwork.c API discrepancies #84
Description
The VxWorks osnetwork.c code differs from the OSAL Library API documentation under some conditions. Even more interesting, the posix and rtems OSAL implementations behave differently from the VxWorks as well.
In osal/src/os/vxworks6/osnetwork.c, the documentation and code for
{{{
int32 OS_NetworkGetID (void)
}}}
don't match when there is no network (e.g. OS_INCLUDE_NETWORK is undefined in osconfig.h).
The c source file function comments are:
{{{
Returns: OS_ERROR if the host id could not be found
a 32 bit host id if success
}}}
The OSAL Library API.pdf has:
{{{
Returns:
OS_ERROR if the operating system calls fail
OS_SUCCESS if success
}}}
''(That OS_SUCCESS looks like a copyNpaste error, all implementations return the host id for successful behavior.)''
But the VxWorks code returns a (valid) host id of zero, instead of OS_ERROR (a -1) or OS_ERR_NOT_IMPLEMENTED (osapi.h).
When looking at the osal/src/os/rtems/osnetwork.c, I see that it returns OS_ERR_NOT_IMPLEMENTED when the OS_INCLUDE_NETWORK is undefined in osconfig.h. That return value isn't documented in the OSAL Library API.pdf or in any code comments. The posix osnetwork.c pays no attention to OS_INCLUDE_NETWORK and always makes the OS-layer network calls (unlike the rtems and vxworks osal's).
Other API surprises:
{{{
int32 OS_NetworkGetHostName (char *host_name, uint32 name_len)
}}}
can return OS_INVALID_POINTER with a NULL pointer arg. Good implementation, but needs documentation.
Note: I didn't find a tie-breaker in the osapi-os-net.h because that common header had no comments. Also, I was unable to find documentation (pdf or code comments) on the meaning of these osapi.h return codes.
'''Initial Recommendations for this ticket:'''
- All OSAL (osnetwork.c) implementations for OS_NetworkGetID() and OS_NetworkGetHostName() should return OS_ERR_NOT_IMPLEMENTED when the OS_INCLUDE_NETWORK is undefined and not even attempt to make OS calls.
- The OSAL Library API.pdf function documentation should be updated to cover all possible return values.
- The separate osnetwork.c documentation should be removed in favor of a common function description in the osapi-os-net.h, which all OSAL implementations use. Its too easy to focus in on one .c source and not realize there is an API discrepancy.
- Document (in the osapi.h and in the OSAL Library API.pdf) the meanings of these common OSAL return codes.