Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "AmigaDOS Vector-Port"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
m (Fixed a few typos found by Colin W.)
Line 1: Line 1:
 
{{WIP}}
  
{{WIP}}
  +
 
== Rationale ==
  
== Rationale ==
   
−
During development of file-systems, developers often need to implement many parts to interface with DOS library rather than concentrate on implementing the actual function of the file-system. With this in mind, the new interface Vector-port simplify this by delegating most of this work to the DOS library, only the feature implementation itself is the file-system's developer charge.
 +
During development of file systems, developers often need to implement many parts to interface with DOS library rather than concentrate on implementing the actual file system functionality. The new Vector-port interface simplifies this by delegating most of this work to the DOS Library. This leaves only the function implementations up to the file system implementer.
   
 
== Introduction ==
  
== Introduction ==
  +
−
In the past (up to version 53.77) DOS library used to communicate with file-systems and handlers using [[AmigaDOS_Packets|DOS packets]]. A DOS packet is merely an [[Exec_Messages_and_Ports#Messages|Exec Message]] with a structure appended in order to pass parameters one way and results in the other. The aim being to stay the most generic possible those parameters are abstracted - which gives more work to the developer when they have to handle the packet.
  
−
Starting with version 53.77 DOS library offers the new API "Vector-Port" for file-systems (i.e. not for handlers). It is basically a [[Exec_Messages_and_Ports#Message_Ports|Message port]] with an associated function list (also called "table of vectors" thus the API name). This way we are freed from many legacy things - BSTRs notably - which let the developer know exactly what he is manipulating.
 +
In the past, DOS library used to communicate with file systems and handlers exclusively using [[AmigaDOS_Packets|DOS packets]]. A DOS packet is merely an [[Exec_Messages_and_Ports#Messages|Exec Message]] with a structure appended in order to pass parameters and results. The aim being to remain as generic as possible with abstracted parameters. This pushes much of the work to the developer when they have to handle the DOS packet.
  +
  +
Starting with version 53.77, DOS Library offers the new "Vector-Port" API for file systems. Note this API is not meant to be used by handlers. It is basically a [[Exec_Messages_and_Ports#Message_Ports|Message port]] with an associated function list (also called "table of vectors" thus the API name). In this way, we are freed from many legacy things (notably BSTRs) and the functions let the developer know exactly what he is manipulating.
   
 
== Legacy Support ==
  
== Legacy Support ==
   
−
Moreover since version 53.95; DOS library provides a DOS packet emulation for legacy applications that used to send DOS packets directly to the file-system's Message Port, this would effectively cause these old applications to break on a complete Vector-Port based file-system. However, this special DOS packet emulation function allow these 'application-sent' DOS packets to be automatically converted to an equivalent Vector-Port call.
 +
Since version 53.95, DOS Library provides DOS packet emulation for legacy applications that still send DOS packets directly to the file system's Message Port. This effectively keeps these old applications from breaking on a complete Vector-Port based file system. This special DOS packet emulation functionality allows these 'application-sent' DOS packets to be automatically converted to equivalent Vector-Port calls.
   
−
== Existing file-system conversion ==
 +
== Existing file system conversion ==
   
−
DOS allows for a step by step conversion of existing file-systems to the Vector-Port API by falling back to sending a DOS packet when any Vector-Port function is NULL or the Vector-Port itself does not validate.
 +
DOS allows for a step by step conversion of existing file systems to the Vector-Port API by falling back to sending a DOS packet when any Vector-Port function is NULL or the Vector-Port itself does not validate. This means that one can convert single functions one at a time by simply adding or removing the function vector from the Vector-Port initialisation table.
−
This means that once can convert single functions at a time by simply adding or removing the function vector from the Vector-Port initialisation table.
  
   
 
== Key points ==
  
== Key points ==
   
−
Formerly a file-system was required to allocate a Message Port, now it only needs to replace this creation by a call to DOS method "AllocDosObject" requesting creation of a Vector-Port and providing it the list of implemented functions. Everything else is automatically handled: for unimplemented functions DOS library will fallback to sending a DOS packet, for the other DOS library will call them directly. It is one of the advantage of this solution: as it uses direct function calls it's substantially faster than sending a message and waiting its handling by the file-system. It is also processed in the caller context thus we benefit from the OS multitasking feature to parallelize calls and there is no context switch anymore.
 +
Formerly a file system was required to allocate a Message Port. Now it only needs to replace this creation by a call to DOS method AllocDosObject() requesting creation of a Vector-Port and providing it the list of implemented functions. Everything else is automatically handled. Any unimplemented functions DOS library will fallback to sending a DOS packet. One of the advantage of this solution is because it uses direct function calls, it is substantially faster than sending a message and waiting for its handling by the file system. It is also processed on the caller's context thus we benefit from the OS multitasking feature to parallelize calls and there is no expensive context switching.
   
 
Example for ACTION_LOCATE_OBJECT DOS packet and the corresponding "Vector-Port" function FSLock():
  
Example for ACTION_LOCATE_OBJECT DOS packet and the corresponding "Vector-Port" function FSLock():
   
  +
<pre>
−
<syntaxhighlight>
  
 
INPUTS (DosPacket method)
  
INPUTS (DosPacket method)
 
dp_Type - (int32) ACTION_LOCATE_OBJECT
  
dp_Type - (int32) ACTION_LOCATE_OBJECT
Line 47: Line 49:
 
RESULT1 - (struct Lock *) Pointer to the lock, NULL on failure.
  
RESULT1 - (struct Lock *) Pointer to the lock, NULL on failure.
 
RESULT2 - (int32) Failure code if RESULT1 == NULL
  
RESULT2 - (int32) Failure code if RESULT1 == NULL
  +
</pre>
−
</syntaxhighlight>
  
   
 
== Developer tool ==
  
== Developer tool ==
   
−
To help with creation of new file-systems FSVPtool creates a ready to use skeleton. This tool should have find its way to the latest SDK but due to packaging time constraint before Amiwest it has not. It will be included in the next or may be published as a stand alone package.
 +
FSVPtool creates a ready to use skeleton to help with creation of new file systems. This tool should be available in the latest SDK.

Revision as of 23:59, 29 November 2013

WIP.png This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally.

Rationale

During development of file systems, developers often need to implement many parts to interface with DOS library rather than concentrate on implementing the actual file system functionality. The new Vector-port interface simplifies this by delegating most of this work to the DOS Library. This leaves only the function implementations up to the file system implementer.

Introduction

In the past, DOS library used to communicate with file systems and handlers exclusively using DOS packets. A DOS packet is merely an Exec Message with a structure appended in order to pass parameters and results. The aim being to remain as generic as possible with abstracted parameters. This pushes much of the work to the developer when they have to handle the DOS packet.

Starting with version 53.77, DOS Library offers the new "Vector-Port" API for file systems. Note this API is not meant to be used by handlers. It is basically a Message port with an associated function list (also called "table of vectors" thus the API name). In this way, we are freed from many legacy things (notably BSTRs) and the functions let the developer know exactly what he is manipulating.

Legacy Support

Since version 53.95, DOS Library provides DOS packet emulation for legacy applications that still send DOS packets directly to the file system's Message Port. This effectively keeps these old applications from breaking on a complete Vector-Port based file system. This special DOS packet emulation functionality allows these 'application-sent' DOS packets to be automatically converted to equivalent Vector-Port calls.

Existing file system conversion

DOS allows for a step by step conversion of existing file systems to the Vector-Port API by falling back to sending a DOS packet when any Vector-Port function is NULL or the Vector-Port itself does not validate. This means that one can convert single functions one at a time by simply adding or removing the function vector from the Vector-Port initialisation table.

Key points

Formerly a file system was required to allocate a Message Port. Now it only needs to replace this creation by a call to DOS method AllocDosObject() requesting creation of a Vector-Port and providing it the list of implemented functions. Everything else is automatically handled. Any unimplemented functions DOS library will fallback to sending a DOS packet. One of the advantage of this solution is because it uses direct function calls, it is substantially faster than sending a message and waiting for its handling by the file system. It is also processed on the caller's context thus we benefit from the OS multitasking feature to parallelize calls and there is no expensive context switching.

Example for ACTION_LOCATE_OBJECT DOS packet and the corresponding "Vector-Port" function FSLock(): 

   INPUTS    (DosPacket method)
	dp_Type - (int32) ACTION_LOCATE_OBJECT
	dp_Arg1 - (BPTR)  lock.
	dp_Arg2 - (BSTR)  object_name. (may also include path)
	dp_Arg3 - (int32) Mode. SHARED_LOCK or EXCLUSIVE_LOCK.
	dp_Arg4 - <unused> 0
	dp_Arg5 - (BSTR)  nameformat - name format indicator value.
	           only if(dp_Arg2==dp_Arg5) then BSTR's are guaranteed to be
	           a nul-terminated string. (53.23)
	RESULT1 - (BPTR)  Lock - (ZERO on failure.)
	RESULT2 - (int32) Failure code if RESULT1 == ZERO

    INPUTS    (FileSystemVectorPort method)
      struct Lock * RESULT1 = FSLock(struct FileSystemVectorPort *fsvp, 
                                     int32 *result2, struct Lock *rel,
                                     CONST_STRPTR name, int32 mode);
	fsvp    - (struct FileSystemVectorPort *) Pointer to the vector port.
	result2 - (int32 *) Pointer to the storage area for RESULT2.
	rel_dir - (struct Lock *) Pointer to the 'name' reference dir lock.
	name    - (CONST_STRPTR) Pointer to the object name.(no path component)
	mode    - (int32) SHARED_LOCK, EXCLUSIVE_LOCK.
	RESULT1 - (struct Lock *) Pointer to the lock, NULL on failure.
	RESULT2 - (int32) Failure code if RESULT1 == NULL

Developer tool

FSVPtool creates a ready to use skeleton to help with creation of new file systems. This tool should be available in the latest SDK.

Retrieved from "http://wiki.amigaos.net/w/index.php?title=AmigaDOS_Vector-Port&oldid=6694"