Network manager callback status codes

[MandusBorjesson]

Hi all!

I am in the process of bumping the zephyr version of my project to 4.2.0, including a move using the Network Manager. I have some questions regarding network manager event callbacks, specifically the info member in the net_mgmt_event_callback struct for WiFi connections.

From what I have been able to figure out, the info member tends to point to whatever value the used driver passes as status to the wifi_mgmt_raise_disconnect_result_event and wifi_mgmt_raise_connect_result_event functions, which both take an int status code. The value is then casted to a wifi_status struct and passed along to the application, ending up in the registered callbacks info member.

I am using an espressif chip and would like a bit more info than a 0/-1 status code out of my callbacks so I am modifying the esp_wifi_drv driver to use the wifi_status union members and their respective enum values.

What puzzles me are the different values that are passed to these functions by different drivers, as there doesn't seem to be any consensus in the driver implementations. For example, espressif's driver uses 0 or -1, Simplelink uses 0or -EIO (stating that they will map the code to wifi_status codes once they are defined) and so on...

Are there any guidelines as to how this status code should be used? I have read through the docs and might be missing something, but I can't seem to find any guidelines. My assumption based on the different status enum values would be the following:

• wifi_mgmt_raise_connect_result_event
  • Use wifi_status.wifi_conn_status values
  • Use this for anything related to connecting to a WiFi network, including successful and failed connection attempts
• wifi_mgmt_raise_connect_result_event
  • Use wifi_status.wifi_disconn_reason values
  • Use this for anything related to disconnecting to a WiFi network, such as the network disappearing or user-initiated disconnect

As mentioned, I will likely modify the esp driver to better fit my needs, but I want to make sure I am not stepping too far out of the design philosophy behind the Network Manager. Are my assumptions reasonable? Is there a reason I don't see other drivers doing this? Any feedback is welcome.

[jukkar]

Are there any guidelines as to how this status code should be used? I have read through the docs and might be missing something, but I can't seem to find any guidelines.

The status code values are not documented in the header file which is unfortunate. From wifi shell code in

zephyr/subsys/net/l2/wifi/wifi_shell.c

Line 300 in c7086c7

static void handle_wifi_connect_result(struct net_mgmt_event_callback *cb)

it can be seen that the status value 0 means success, and < 0 an error (preferably mapped to -errno value). This should be documented properly in the header file. @MandusBorjesson would you be able to send a PR fixing this and add proper documentation to it?

[jukkar]

cc: @krish2718 what is your take on this?

[krish2718]

Yes, I agree. The reason why it was a union of generic int status vs. proper Enumerations it to give drivers flexibility to report. But most are just using int status as a standard way by returning errno. It would be good to migrate to enumerations instead of Linux style -ve for error or convert this to a struct from union and in case of status < 0 then one can use the failure_reason that is an enumerations, so, something like (crude, I just typed to demonstrate)

/* TODO: Rename status->failure*/
struct wifi_failure_codes {
	union {
		/** Connection status */
		enum wifi_conn_status conn_status;
		/** Disconnection reason status */
		enum wifi_disconn_reason disconn_reason;
		/** Access point status */
		enum wifi_ap_status ap_status;
	};
};

struct wifi_status {
  int status; /* 0 - success, < 0 - generic failure, see errno.h */
  struct wifi_failure_codes wifi_fail_reason; /* 
}

This way we can pass generic error codes as well as Wi-Fi specific errors too, WDYT?

[MandusBorjesson]

In the example, how would one use the wifi_fail_reason?

In my mind, status = 0 would indicate that it can be ignored. For status < 0 it might(?) be set and the value can be interpreted as an errno. Does the combination of an errno and a wifi_fail_reason add anything that cant be communicated without the errno?

[krish2718]

think of it like a tuple (generic_error, wifi_error), generic error is a guard to wifi_error,

1. (-ENOBUFS, NA)
2. (0, WIFI_REASON_DISCONN_INACTIVITY)

[MandusBorjesson]

Thats a good way of looking at it, I like this suggestion