Revision 5 - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:25:52Z

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

← Older revision		Revision as of 19:25, 26 January 2025
Line 87:		Line 87:
	I propose the following hook messages to be used :		I propose the following hook messages to be used :

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SANA2HookMsg		struct SANA2HookMsg
	{		{
Line 99:		Line 99:
	For copying operations the message would look like this:		For copying operations the message would look like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SANA2CopyHookMsg		struct SANA2CopyHookMsg
	{		{
Line 128:		Line 128:
	For logging operations the message would look like this:		For logging operations the message would look like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SANA2LogHookMsg		struct SANA2LogHookMsg
	{		{
Line 177:		Line 177:
	The hook function itself would be invoked with the following parameters:		The hook function itself would be invoked with the following parameters:

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

Steven Solie: /* Introduction */

2012-05-10T20:55:30Z

Introduction

← Older revision		Revision as of 20:55, 10 May 2012
Line 8:		Line 8:
	The last changes proposed for the SANA-II networking driver standard were intended to address the demands of dial-up networking. A new issue has come up which concerns the application and deployment of PowerPC native networking drivers. So far the SANA-II standard only caters well for the Motorola 68000 platform, and the only way to support it on the PowerPC involves a considerable overhead. This is what the following proposal intends to address.		The last changes proposed for the SANA-II networking driver standard were intended to address the demands of dial-up networking. A new issue has come up which concerns the application and deployment of PowerPC native networking drivers. So far the SANA-II standard only caters well for the Motorola 68000 platform, and the only way to support it on the PowerPC involves a considerable overhead. This is what the following proposal intends to address.

	Please feel free to comment; you can contact me through the ~~e-mail~~ ~~address~~ ~~given~~ ~~in the headline of this document~~. Note that the issues discussed in this document are just a list of proposed changes.		Please feel free to comment; you can contact me through the [http://www.amigaos.net/contact AmigaOS contact form]. Note that the issues discussed in this document are just a list of proposed changes.

	== The problem: parameter passing to the copying functions ==		== The problem: parameter passing to the copying functions ==

Steven Solie: /* Authors */

2012-05-10T20:30:41Z

Authors

← Older revision		Revision as of 20:30, 10 May 2012
Line 2:		Line 2:

	Hook-based callback function extensions for SANA-II (SANA-IIR5) <br />		Hook-based callback function extensions for SANA-II (SANA-IIR5) <br />
	by ~~[mailto:sana2feedback@amiga.com?subject=Re:%20SANA-IIR5%20proposal~~ Olaf Barthel] and Heinz Wrobel		by Olaf Barthel and Heinz Wrobel

	== Introduction ==		== Introduction ==

Steven Solie: /* Data structures */

2012-05-09T19:52:22Z

Data structures

← Older revision		Revision as of 19:52, 9 May 2012
Line 177:		Line 177:
	The hook function itself would be invoked with the following parameters:		The hook function itself would be invoked with the following parameters:

			<syntaxhighlight>
	<pre>
	result = hook_function(hook,sana2req,sana2hookmsg)		result = hook_function(hook,sana2req,sana2hookmsg)

Line 183:		Line 183:
	struct IOSana2Req *sana2req,		struct IOSana2Req *sana2req,
	struct SANA2HookMsg *sana2hookmsg);		struct SANA2HookMsg *sana2hookmsg);
			</syntaxhighlight>
	</pre>

	Note that the result would not necessarily be of type <tt>ULONG</tt>. It would be a 32 bit value, which would either be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or the pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).		Note that the result would not necessarily be of type <tt>ULONG</tt>. It would be a 32 bit value, which would either be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or the pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

Steven Solie: /* The problem: parameter passing to the copying functions */

2012-05-02T22:20:17Z

The problem: parameter passing to the copying functions

← Older revision		Revision as of 22:20, 2 May 2012
Line 47:		Line 47:
	system memory functions (since those functions rely on Forbid() to		system memory functions (since those functions rely on Forbid() to
	protect themselves) and that you must not compile this function		protect themselves) and that you must not compile this function
	with stack checking enabled. See the ~~RKM:Libraries~~ Exec:Interupts		with stack checking enabled. See the Exec Interupts
	chapter for more details on what is legal in a routine called from		chapter for more details on what is legal in a routine called from
	an interupt handler.		an interupt handler.

Steven Solie: /* Changes */

2012-05-02T15:44:56Z

Changes

← Older revision		Revision as of 15:44, 2 May 2012
Line 320:		Line 320:

	== Changes ==		== Changes ==

			02-May-2012:

			* Conversion to MediaWiki format.

	22-Mar-2004:		22-Mar-2004:

Steven Solie: /* New data structures and commands */

2012-05-02T15:44:08Z

New data structures and commands

← Older revision		Revision as of 15:44, 2 May 2012
Line 80:		Line 80:
	** <tt>S2_DMACopyToBuff64</tt>		** <tt>S2_DMACopyToBuff64</tt>
	** <tt>S2_DMACopyFromBuff64</tt>		** <tt>S2_DMACopyFromBuff64</tt>


	There are three 'flavours' of the data copying functions. These cater for certain buffer memory alignment requirements which the underlying hardware requires or which can be used to boost transfer efficiency. For the direct memory access functions there are two variants which cater for certain memory alignment requirements in the same manner as the copying functions.		There are three 'flavours' of the data copying functions. These cater for certain buffer memory alignment requirements which the underlying hardware requires or which can be used to boost transfer efficiency. For the direct memory access functions there are two variants which cater for certain memory alignment requirements in the same manner as the copying functions.
Line 88:		Line 87:
	I propose the following hook messages to be used :		I propose the following hook messages to be used :

			<syntaxhighlight>
	~~<pre>~~ struct SANA2HookMsg		struct SANA2HookMsg
	{
			{
	ULONG shm_Method;
	ULONG ~~shm_MsgSize~~;		ULONG shm_Method;
			ULONG shm_MsgSize;
⚫	};</pre>
			};
			</syntaxhighlight>

	In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can a be request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is (for future enhancements which may cause the data structure to grow).		In this data structure the <tt>shm_Method</tt> field would indicate the task to be performed. This can a be request to copy data or to store a log message. The <tt>shm_MsgSize</tt> field tells you how large the data structure is (for future enhancements which may cause the data structure to grow).

	For copying operations the message would look like this:		For copying operations the message would look like this:

			<syntaxhighlight>
	~~<pre>~~ struct SANA2CopyHookMsg		struct SANA2CopyHookMsg
	{
			{
	ULONG schm_Method;
	ULONG ~~schm_MsgSize~~;		ULONG schm_Method;
			ULONG schm_MsgSize;

		⚫	APTR schm_To;
		⚫	APTR schm_From;
		⚫	ULONG schm_Size;
			};
			</syntaxhighlight>

⚫	APTR schm_To;
⚫	APTR schm_From;
⚫	ULONG schm_Size;
⚫	};</pre>
	The structure members would be used as follows:		The structure members would be used as follows:

Line 123:		Line 128:
	For logging operations the message would look like this:		For logging operations the message would look like this:

			<syntaxhighlight>
	~~<pre>~~ struct SANA2LogHookMsg		struct SANA2LogHookMsg
	{
			{
	ULONG slhm_Method;
	ULONG ~~slhm_MsgSize~~;		ULONG slhm_Method;
			ULONG slhm_MsgSize;

		⚫	ULONG slhm_Priority;
		⚫	STRPTR slhm_Name;
		⚫	STRPTR slhm_Message;
			};
			</syntaxhighlight>

⚫	ULONG slhm_Priority;
⚫	STRPTR slhm_Name;
⚫	STRPTR slhm_Message;
⚫	};</pre>
	The structure members would be used as follows:		The structure members would be used as follows:

Line 169:		Line 177:
	The hook function itself would be invoked with the following parameters:		The hook function itself would be invoked with the following parameters:

			<pre>
	~~<pre>~~ result = hook_function(hook,sana2req,sana2hookmsg)		result = hook_function(hook,sana2req,sana2hookmsg)
	D0 A0 A2 A1

	ULONG hook_function(struct Hook *hook,		ULONG hook_function(struct Hook *hook,
	struct IOSana2Req *sana2req,		struct IOSana2Req *sana2req,
	struct SANA2HookMsg *sana2hookmsg);~~</pre>~~		struct SANA2HookMsg *sana2hookmsg);
		⚫	</pre>

	Note that the result would not necessarily be of type <tt>ULONG</tt>. It would be a 32 bit value, which would either be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or the pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).		Note that the result would not necessarily be of type <tt>ULONG</tt>. It would be a 32 bit value, which would either be a boolean result code (for <tt>CopyFromBuff</tt>, <tt>CopyToBuff</tt> and their like) or the pointer to a memory address (for <tt>DMACopyToBuff</tt>, <tt>DMACopyFromBuff</tt> and their like).

Line 183:		Line 193:
	The command is tentatively defined as follows:		The command is tentatively defined as follows:

			<pre>
	~~<pre>~~sana2.device/S2_SANA2HOOK sana2.device/S2_SANA2HOOK		sana2.device/S2_SANA2HOOK sana2.device/S2_SANA2HOOK

	NAME		NAME
Line 281:		Line 292:
	This field is to be treated as private by a protocol stack.		This field is to be treated as private by a protocol stack.
	IOSana2Req structures may be duplicated by copying		IOSana2Req structures may be duplicated by copying
	ios2_BufferManagement, io_Device, and io_Unit.~~</pre>~~		ios2_BufferManagement, io_Device, and io_Unit.
		⚫	</pre>

	The new command value is defined as follows:		The new command value is defined as follows:

			<pre>
	~~<pre>~~ #define S2_SANA2HOOK 0xC008~~</pre>~~		#define S2_SANA2HOOK 0xC008
		⚫	</pre>

	The new error code is defined as follows:		The new error code is defined as follows:

			<pre>
	~~<pre>~~ #define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */~~</pre>~~		#define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */
			</pre>

	== Application and driver software use of the new functions ==		== Application and driver software use of the new functions ==

Steven Solie: /* 6. Changes */

2012-04-24T14:45:13Z

6. Changes

← Older revision		Revision as of 14:45, 24 April 2012
Line 301:		Line 301:
	Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.		Note that the <tt>ios2_BufferManagement</tt> field provided by the driver on <tt>OpenDevice()</tt> time in conjunction with <tt>io_Device</tt> and <tt>io_Unit</tt> is the unique identifier for all requests coming from this protocol stack until <tt>CloseDevice()</tt>. The driver must not ever change the <tt>ios2_BufferManagement</tt> field for a protocol stack at run time, even if <tt>S2_SANAHOOK</tt> is called to request extended features.

	== 6. Changes ==		== Changes ==

	22-Mar-2004:		22-Mar-2004:

Steven Solie: /* 5. Caveats */

2012-04-24T14:45:02Z

5. Caveats

← Older revision		Revision as of 14:45, 24 April 2012
Line 295:		Line 295:
	If the new <tt>Hook</tt>-based callback functions are to be used, then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must not invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.		If the new <tt>Hook</tt>-based callback functions are to be used, then the driver must invoke the Hooks via <tt>utility.library/CallHookPkt</tt>. It must not invoke the hook functions through local assembly language stubs or the <tt>amiga.lib/CallHook</tt> and <tt>amiga.lib/CallHookA</tt> functions.

	== 5. Caveats ==		== Caveats ==

	The functionality proposed above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore recommend to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.		The functionality proposed above suggests that one could do entirely without the <tt>TagItem</tt> list passed in at <tt>OpenDevice()</tt> time. However, at this time it is hard to tell how existing driver software will react to empty <tt>TagItem</tt> lists or even a NULL pointer in the <tt>IOSana2Req->ios2_BufferManagement</tt> field. It is therefore recommend to always provide for a <tt>TagItem</tt> list which includes proper (i.e. they must point to working functions and may not be <tt>NULL</tt>) function pointers for the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags. Once the device has been opened successfully, the next step is to try and install the copy <tt>Hook</tt> through the proposed <tt>S2_SANA2HOOK</tt> command. If the command fails, the application can still expect that the <tt>S2_CopyToBuff</tt> and <tt>S2_CopyFromBuff</tt> tags supplied at <tt>OpenDevice()</tt> time will work.

Steven Solie: /* 4. Application and driver software use of the new functions */

2012-04-24T14:44:49Z

4. Application and driver software use of the new functions

← Older revision		Revision as of 14:44, 24 April 2012
Line 289:		Line 289:
	<pre> #define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */</pre>		<pre> #define S2WERR_FUNCTIONS_MISSING 24 /* mandatory copy functions are missing */</pre>

	== 4. Application and driver software use of the new functions ==		== Application and driver software use of the new functions ==

	Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time it is recommend that drivers always examine these parameters and do not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.		Since plenty of software exists which uses the 'traditional' <tt>TagItem</tt> list provided at <tt>OpenDevice()</tt> time it is recommend that drivers always examine these parameters and do not expect a <tt>S2_SANA2HOOK</tt> command to be sent later.