AmigaDOS Vector-Port

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 to the DOS library it self, only the feature implementation itself is the file-system's developer charge.

Introduction

In the past (up to version 53.77) DOS library used to communicate with file-systems and handlers using DOS packets. A DOS packet is merely an 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 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.

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.

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 once can convert single functions 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: 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.

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

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.