AmigaDOS Vector-Port

Rationale

During development of file systems, the developer often needs to write a lot of code just to interface with DOS library. The new Vector-port interface simplifies this by delegating most of this interface work to the DOS Library. This means that the developer writing the file system can concentrate on implementing the functions required.

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 exclusively for use by file systems. 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.

More information

For further details and example code, refer to the autodoc: dos.dospackets.doc