SANA-II Revision 7 - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:34:56Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:34, 26 January 2025
Line 30:		Line 30:
	As when opening any other Exec device, on the call to OpenDevice() a SANA-II device receives an IORequest structure which the device initializes for the opener's use. The opener must copy this structure if it desires to use multiple asynchronous requests. The SANA-II IORequest is defined as follows:		As when opening any other Exec device, on the call to OpenDevice() a SANA-II device receives an IORequest structure which the device initializes for the opener's use. The opener must copy this structure if it desires to use multiple asynchronous requests. The SANA-II IORequest is defined as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct IOSana2Req		struct IOSana2Req
	{		{
Line 236:		Line 236:
	The hook function itself is invoked with the following parameters:		The hook function itself is invoked with the following parameters:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	result = hook_function(hook, sana2req, sana2hookmsg)		result = hook_function(hook, sana2req, sana2hookmsg)

Line 250:		Line 250:
	The following hook messages are to be used:		The following hook messages are to be used:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SANA2HookMsg		struct SANA2HookMsg
	{		{
Line 264:		Line 264:
	For copying operations the message is:		For copying operations the message is:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SANA2CopyHookMsg		struct SANA2CopyHookMsg
	{		{
Line 298:		Line 298:
	For logging operations the message is:		For logging operations the message is:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SANA2LogHookMsg		struct SANA2LogHookMsg
	{		{
Line 367:		Line 367:
	If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:		If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	log_hook_function(hook, reserved, message)		log_hook_function(hook, reserved, message)

Line 376:		Line 376:
	The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:		The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct S2LogMessage		struct S2LogMessage
	{		{
Line 606:		Line 606:
	S2_TRACKTYPE tells the device driver to gather statistics for a particular packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type causes the driver to use additional resources). S2_GETTYPESTATS returns any statistics accumulated by the driver for a type being tracked (stats are lost when a type is S2_UNTRACKTYPE'd). Drivers are required to implement the functionality of type tracking. The stats are returned in a struct Sana2PacketTypeStats:		S2_TRACKTYPE tells the device driver to gather statistics for a particular packet type. S2_UNTRACKTYPE tells it to stop (keeping statistics by type causes the driver to use additional resources). S2_GETTYPESTATS returns any statistics accumulated by the driver for a type being tracked (stats are lost when a type is S2_UNTRACKTYPE'd). Drivers are required to implement the functionality of type tracking. The stats are returned in a struct Sana2PacketTypeStats:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2PacketTypeStats		struct Sana2PacketTypeStats
	{		{
Line 630:		Line 630:
	returns global statistics kept by the driver. Drivers are required to keep all applicable statistics. Since all are applicable to most hardware, most drivers will maintain all statistics. The stats are returned in a struct Sana2DeviceStats:		returns global statistics kept by the driver. Drivers are required to keep all applicable statistics. Since all are applicable to most hardware, most drivers will maintain all statistics. The stats are returned in a struct Sana2DeviceStats:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2DeviceStats		struct Sana2DeviceStats
	{		{
Line 660:		Line 660:
	returns any special statistics kept by a particular driver. Each new wire type will have a set of documented, required statistics for that wire type and a standard set of optional statistics for that wire type (optional because they might not be available from all hardware). The data returned by S2_GETSPECIALSTATS will require wire-specific interpretation. See <devices/sana2specialstats.h> on page devices<sub>s</sub>ana2specialstats<sub>p</sub>age for currently defined special statistics. The statistics are returned in the following structures:		returns any special statistics kept by a particular driver. Each new wire type will have a set of documented, required statistics for that wire type and a standard set of optional statistics for that wire type (optional because they might not be available from all hardware). The data returned by S2_GETSPECIALSTATS will require wire-specific interpretation. See <devices/sana2specialstats.h> on page devices<sub>s</sub>ana2specialstats<sub>p</sub>age for currently defined special statistics. The statistics are returned in the following structures:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2SpecialStatRecord		struct Sana2SpecialStatRecord
	{		{
Line 676:		Line 676:
	: An identifying, null-terminated string for the statistic. Should be plain ASCII with no formatting characters.		: An identifying, null-terminated string for the statistic. Should be plain ASCII with no formatting characters.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2SpecialStatHeader		struct Sana2SpecialStatHeader
	{		{
Line 700:		Line 700:
	Driver users will want to use S2_DEVICEQUERY to determine the MTU and other characteristics of the network. The structure returned from S2_DEVICEQUERY is defined as:		Driver users will want to use S2_DEVICEQUERY to determine the MTU and other characteristics of the network. The structure returned from S2_DEVICEQUERY is defined as:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2DeviceQuery		struct Sana2DeviceQuery
	{		{
Line 881:		Line 881:
	=== sana2wireless.h ===		=== sana2wireless.h ===

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	#ifndef DEVICES_SANA2WIRELESS_H		#ifndef DEVICES_SANA2WIRELESS_H
	#define DEVICES_SANA2WIRELESS_H		#define DEVICES_SANA2WIRELESS_H
Line 1,466:		Line 1,466:
	To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:		To bridge this gap, I propose a new command which will make a driver connect to its link layer and go online, which uses the following data structure:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2Connection		struct Sana2Connection
	{		{
Line 1,489:		Line 1,489:
	This list contains options, to be used during the connection process. Each node has the following format:		This list contains options, to be used during the connection process. Each node has the following format:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2ConnectionOption		struct Sana2ConnectionOption
	{		{
Line 1,525:		Line 1,525:
	The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:		The <tt>reserved</tt> parameter '''must''' be <tt>NULL</tt>. The <tt>s2cm</tt> parameter points to a data structure, as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2ConnectionMessage		struct Sana2ConnectionMessage
	{		{
Line 2,132:		Line 2,132:
	There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:		There already exists a SANA-II command for querying global device statistics (<tt>S2_GETGLOBALSTATS</tt>) which should be common to all kinds of networking devices. Statistics that are particular to a certain device type are intended to be returned through the <tt>S2_GETSPECIALSTATS</tt> command. I feel that these mechanisms both fail to cater well enough for dial-up or session-oriented networking applications such as PPP or PPPoE. Since the data structure used by <tt>S2_GETGLOBALSTATS</tt> is of a fixed size and not intended to accomodate for new fields, I propose to introduce a new command which uses a different data structure, as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2ExtDeviceStats		struct Sana2ExtDeviceStats
	{		{
Line 2,759:		Line 2,759:
	The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:		The SANA-II standard already allows for statistics to be returned on the amount of data that has passed through a driver. Unfortunately, that information is not very accurate in that no information is provided on the time span in which the data was accumulated. Such information would be helpful in trying to determine as accurately as possible how large the data throughput actually is. I therefore propose a new command which can be used to obtain that information, which uses the following data structure:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Sana2ThroughputStats		struct Sana2ThroughputStats
	{		{

Steven Solie: /* Best buffer management */

2012-12-21T18:06:07Z

Best buffer management

← Older revision		Revision as of 18:06, 21 December 2012
Line 230:		Line 230:
	Alternatively, if a hook function is used, the operating system may be able to decide whether the function to be invoked needs emulating or called directly. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.		Alternatively, if a hook function is used, the operating system may be able to decide whether the function to be invoked needs emulating or called directly. The <tt>Hook</tt> effectively works as an abstraction which makes the function invocation platform independent.

	The following standard wraps the copying functions into the standardized <tt>Hook</tt> interface.		The following standard wraps the copying and logging functions into the standardized <tt>Hook</tt> interface.

	==== The hook function ====		==== The hook function ====
Line 293:		Line 293:
	; schm_Size		; schm_Size
	: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.		: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.

	==== Filtering operations ====

	TBD

	==== Logging operations ====		==== Logging operations ====

Steven Solie: /* Best buffer management */

2012-12-21T18:04:49Z

Best buffer management

@@ Line 231: / Line 231: @@
 The following standard wraps the copying functions into the standardized <tt>Hook</tt> interface.
 === Data structures ===
@@ Line 336: / Line 350: @@
 : Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>slhm_Message</tt> member must never be <tt>NULL</tt>.
 : All message texts shall preferably be formatted in the current user's locale. If that is not possible, the english language shall be used. <tt>slhm_Name</tt> and <tt>slhm_Message</tt> shall only contain printable characters.
 === Application and driver software use of the new functions ===

Steven Solie: /* Driver event logging */

2012-12-21T18:03:36Z

Driver event logging

@@ Line 397: / Line 397: @@
 ;s2lm_Priority
 : The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):
 All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.
@@ Line 445: / Line 428: @@
 This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.
 = Packet Type =

Steven Solie: /* Copying operations */

2012-12-21T18:00:13Z

Copying operations

← Older revision		Revision as of 18:00, 21 December 2012
Line 279:		Line 279:
	; schm_Size		; schm_Size
	: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.		: Equivalent to the <tt>n</tt> parameter of the <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt>, functions.

			==== Filtering operations ====

			TBD

	==== Logging operations ====		==== Logging operations ====

Steven Solie: /* Driver event logging */

2012-12-21T17:57:44Z

Driver event logging

← Older revision		Revision as of 17:57, 21 December 2012
Line 362:		Line 362:

	== Driver event logging ==		== Driver event logging ==

			A driver may want to report an important event for the user to see. Adding a log message to a file or opening a window to display a message in may not be the optimum approach as the user may be unaware of the context into which the message belongs. It may be advisable for the driver to use the message reporting and logging facilities used by the client software that uses its services, such as a TCP/IP stack. The <tt>S2_Log</tt> callback hook is intended to provide for such a link.

			If present, the driver must use this callback hook rather than whatever logging methods it implements itself. Note that unlike the other SANA-II callbacks, this is a regular hook, as to be invoked using <tt>utility.library</tt>/<tt>CallHookPkt()</tt>. The hook function is invoked using the following parameters:

			<syntaxhighlight>
			log_hook_function(hook, reserved, message)

			void log_hook_function(struct hook * hook,APTR reserved,
			struct S2LogMessage * message);
			</syntaxhighlight>

			The <tt>reserved</tt> parameter '''must''' be set to <tt>NULL</tt>. The <tt>S2LogMessage</tt> structure passed as the third parameter looks like this:

			<syntaxhighlight>
			struct S2LogMessage
			{
			LONG s2lm_Size;
			ULONG s2lm_Priority;
			STRPTR s2lm_Name;
			STRPTR s2lm_Message;
			};
			</syntaxhighlight>

			The individual structure members serve the following functions:

			; s2lm_Size
			: Size of the <tt>S2LogMessage</tt> structure, in bytes. The idea is to extend this data structure in the future, and the size stored in here tells you how long the structure is. The size '''must''' always be >= 16.

			;s2lm_Priority
			: The smaller this value, the more important the message to be logged or displayed. The following priority levels are defined (similar to the Unix <tt>syslog()</tt> mechanism):

			<tt>#define S2LOG_Emergency 0</tt>

			A panic condition.

			<tt>#define S2LOG_Alert 1</tt>

			A condition that should be corrected immediately.

			<tt>#define S2LOG_Critical 2</tt>

			Critical conditions.

			<tt>#define S2LOG_Error 3</tt>

			A plain error.

			<tt>#define S2LOG_Warning 4</tt>

			A warning message.

			<tt>#define S2LOG_Notice 5</tt>

			Conditions that are not error conditions, but should possibly be handled specially.

			<tt>#define S2LOG_Information 6</tt>

			An informational message.

			<tt>#define S2LOG_Debug 7</tt>

			Messages that contain information normally of use only when debugging.

			<tt>s2lm_Name</tt>

			Pointer to a <tt>NUL</tt>-terminated string which identifies the source of this message. This can be <tt>NULL</tt> in which case the name is treated as being unknown.

			<tt>s2lm_Message</tt>

			Pointer to a <tt>NUL</tt>-terminated string which contains the log message. The text should not contain any formatting characters such as line feeds or carriage returns. The <tt>s2lm_Message</tt> member '''must never''' be <tt>NULL</tt>.

			All error messages issued by the device driver should use the current system locale wherever this is possible. The purpose of an error message is, after all, to assist the user in recovering from the error. Which may be difficult if the user does not even know the language in which the message is written.

			The log message string is valid until the log hook function returns. If the driver needs to retain the message any longer, it must make a copy of it.

			Since the client software into which the log hook calls may have to allocate memory to hold and display the log message, the log hook '''must not''' be called from interrupt code. The log hook shall not <tt>Wait()</tt> and it shall assume only a <tt>Task</tt> calling context of unknown priority. <tt>dos.library</tt> functions may not be called. Also, stack space is provided only to call <tt>exec.library</tt> and <tt>utility.library</tt> functions. The callback shall not place excessive data on the stack. Stack space should be considered limited and the callback should be designed to be fast and short.

			This hook is installed at <tt>OpenDevice()</tt> time, which means that the hook is used for the unit that was opened, and not just for the I/O request it was opened with. The hook must remain installed until the I/O request that installed it is eventually used to close the device. When this happens, the device should fall back to use no log hook at all. No nesting is permitted or required.

			I propose that the following number should be assigned:

			<tt>#define S2_Log (S2_Dummy + 12)</tt>

	= Packet Type =		= Packet Type =

Steven Solie: /* S2_Log */

2012-12-21T17:56:32Z

S2_Log

@@ Line 3,172: / Line 3,172: @@
         go into read processing of the protocol stack and waste CPU time even
         though they could have been easily identified on arrival.</pre>
 = Ethernet description =

Steven Solie: /* Packet filtering */

2012-12-21T17:55:39Z

Packet filtering

← Older revision		Revision as of 17:55, 21 December 2012
Line 359:		Line 359:
	== Packet filtering ==		== Packet filtering ==

	~~What does packet filtering do?~~ With the original "SANA-II Network Device Driver Specification", a protocol stack could open a device and ask for certain packet types. It got all the packets that matched this type. As it turned out, this could be mighty inefficient if there were packets that the protocol stack did not use at all. These would go into read processing of the protocol stack and waste CPU time even though they could have been easily identified on arrival.		With the original "SANA-II Network Device Driver Specification", a protocol stack could open a device and ask for certain packet types. It got all the packets that matched this type. As it turned out, this could be mighty inefficient if there were packets that the protocol stack did not use at all. These would go into read processing of the protocol stack and waste CPU time even though they could have been easily identified on arrival.

			== Driver event logging ==

	= Packet Type =		= Packet Type =

Steven Solie: /* Buffer Management */

2012-12-21T17:53:17Z

Buffer Management

← Older revision		Revision as of 17:53, 21 December 2012
Line 167:		Line 167:

	{\| class="wikitable"		{\| class="wikitable"
	\|+ Logging messages from the ~~protocol stack buffer~~		\|+ Logging messages from the driver
	! Tag		! Tag
	! Description		! Description

Steven Solie: /* Buffer Management */

2012-12-21T17:52:42Z

Buffer Management

← Older revision		Revision as of 17:52, 21 December 2012
Line 172:		Line 172:
	\|-		\|-
	\| S2_Log (optional)		\| S2_Log (optional)
	\| This is a pointer to a standard Hook to be called ?		\| This is a pointer to a standard Hook to be called when the driver logs events.
	\|}		\|}