NASD Programmer's Documentation
Transport

As a research prototype, the NASD drive is intended to be used in a variety of network schema. For this reason, it supports multiple data transport mechanisms. To avoid duplicating code to support multiple transport mechanisms, transport code is separated from the "real" code which dispatches NASD operations. Each NASD operation has an internal function which actually performs the work associated with the operation. That mapping is as follows:

OperationInternal function
noop n/a
sync nasd_odc_flush_dirty()
initialize drive keys nasd_security_initialize_dr()
create partition nasd_od_create_partition()
create object nasd_obj_create()
get object attributes nasd_obj_getattr()
read object nasd_obj_read_simple()
write object nasd_obj_write_simple()
set object attributes nasd_obj_setattr()
force object to stable store nasd_obj_flush()
delete object nasd_obj_remove()
change drive keys nasd_security_change_key_drive()
eject object from drive cache nasd_obj_eject()

For many operations, separating transport from implementation is simple. For example, the get-object-attributes operation can receive its arguments and unmarshall them from any network-canonical ordering that may be in use, execute nasd_obj_getattr(), marshall the results, and transmit them. Other operations, such as read and write, are somewhat more complex. These operations wish to stream data to or from clients, which means that the transport system must be invoked during the execution of the logical operation.

To support these data-streaming operations, the drive defines a type nasd_procpipe_t. This structure is defined as:

struct nasd_procpipe_s {
  void            *state;
  nasd_status_t  (*push)(void *, void *, nasd_len_t);
  nasd_status_t  (*pull)(void *, void *, nasd_len_t, nasd_len_t *);
};
Any such data-streaming function (for example, nasd_obj_read_simple()), receives a nasd_procpipe_t as an argument. The pull function is used to stream data in from a client. The push function is used to stream data out to a client. The first argument to both these functions must always be the state field of the nasd_procpipe_t. The second is the buffer which is the source or target of the data to move. The third is the number of bytes to move in this operation. The pull function takes an additional fourth argument, which is a pointer to a nasd_len_t. This is used to return the number of bytes successfully retrieved from the network to the caller. Both functions return a nasd_status_t which indicates the success or failure of the operation.

The code implementing the transport mechanism is responsible for doing the following:
  • receiving requests from clients
  • decoding those requests to determine the specific operation to be performed
  • decoding the arguments of the request
  • performing any security checks necessary
  • calling the appropriate dispatch function for the request (as enumerated in the table above)
  • providing a nasd_procpipe_t to the dispatch function, if data streaming is required
  • encoding results for clients
  • transmitting results for clients
  • performing any encryption or decryption mandated by the security level of the request
  • One example of a transport mechanism is DCE-RPC. The file nasd_od_ops.c provides the drive mechanisms for DCE-RPC. When requests come in, their arguments are decrypted and converted to host-ordering. The dispatch function is called, and the results are marshalled to network-ordering and encrypted. When DCE exceptions are caught, an error is returned to the client. If data streaming is necessary, nasd_od_dce_push() or nasd_od_dce_pull() are provided as streaming functions. These are wrappers around DCE's similar push/pull mechanism. The actual DCE pipe is passed as the state field of the nasd_procpipe_t, giving nasd_od_dce_push() and nasd_od_dce_pull() easy access to the DCE pipe. These functions similarly trap DCE exceptions, and return errors accordingly to their callers, allowing for graceful error recovery.


    <--- ---> ^<br>|<br>|
    Drive structure Drive physical layout NASD Programmer's Documentation