CACHE_SPEC revision fcf3ce441efd61da9bb2884968af01cb7c1452cc
5cd4555ad444fd391002ae32450572054369fd42Rob Austein# CDDL HEADER START
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein# The contents of this file are subject to the terms of the
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson# Common Development and Distribution License (the "License").
26e2a07a0b6a3b1eccef82ba31270d0c54ad4f06Mark Andrews# You may not use this file except in compliance with the License.
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson# or http://www.opensolaris.org/os/licensing.
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson# See the License for the specific language governing permissions
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson# and limitations under the License.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews# When distributing Covered Code, include this CDDL HEADER in each
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews# If applicable, add the following below this CDDL HEADER, with the
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews# fields enclosed by brackets "[]" replaced with your own identifying
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews# information: Portions Copyright [yyyy] [name of copyright owner]
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews# CDDL HEADER END
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews# Copyright 2008 Sun Microsystems, Inc. All rights reserved.
5cd4555ad444fd391002ae32450572054369fd42Rob Austein# Use is subject to license terms.
f202f2587b9ba4753afba49b796f599cc12b4d0fAndreas Gustafsson# $Id: CACHE_SPEC,v 3.6.0.0 1998/01/05 22:55:19 idumois Exp $
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein "sd" cache layer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein ----------------
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe "sd" layer provides a common interface to the functionality
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeindescribed below. It will also allow switching to a direct to disk
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinversion, so that a new cache module could be loaded.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe functions are basically the same as those below,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinbut named without the leading underscore.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein(ie sd_alloc_buf instead of _sd_alloc_buf)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein "sdbc" -- storage device block cache (aka blkc)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein -----------------------------------------------
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#include "uts/sd/sdbc/sd_cache.h" /* for SDBC interface */
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews#include "sys/sd/sd.h" /* for generic SD interface */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein(all interaction is in terms of the buf_handle.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinCurrently buf_handle is declared as:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#define _SD_MAX_BLKS 64
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#define _SD_MAX_FBAS (_SD_MAX_BLKS << FBA_SHFT)
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrewstypedef struct _sd_buf_handle {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int bh_cd; /* actually bh_buf.sb_cd */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int bh_fba_pos; /* bh_buf.sb_pos */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int bh_fba_len; /* bh_buf.sb_len */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int bh_flag; /* bh_buf.sb_flag */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int bh_error; /* bh_buf.sb_error */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_vec_t bh_bufvec[_SD_MAX_BLKS]; /* bh_buf.sb_vec */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*bh_disconnect_cb)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*bh_read_cb)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*bh_write_cb)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein} _sd_buf_handle_t;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintypedef struct sd_vec_s { /* Scatter gather element */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unsigned char *sv_addr; /* Virtual address of data */
c6d4f781529d2f28693546b25b2967d44ec89e60Mark Andrews unsigned int sv_vme; /* VME address of data */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int sv_len; /* Data length in bytes */
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe upper level routines should reference only: handle->bh_error,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinhandle->bh_bufvec The bh_bufvec is an array of _sd_vec_t with the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlast item in the array having a NULL bufaddr.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinIMPORTANT: The handle should be treated read-only and never be modified.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 1) Multiple accesses to a single file will be supported.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (Side effect: If a process owning cache blocks of a files attempts
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to allocate overlapping cache blocks, it will be a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein deadlock condition.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 2) Multiple writes to an allocated block will be supported. It
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is no longer necessary to free and re-allocate between writes.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 3) _SD_NOBLOCK is equivalent of async_io -- the io will be initiated
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if required with the call returning _SD_PENDING. A callback
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (read or write) will be called at io end action.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 4) Disconnect hints to ckd will be provided by the use of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein either psema or thread_bind() when io needs to be initiated.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_pos = disk block number, each block being 512 bytes.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_len = len in disk blocks, each block being 512 bytes.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Thus, 512 bytes = 1 fba_len, 1024 = 2 fba_len etc...
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_WRTHRU: write through mode.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This hint can be set on a node, a device or per access.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_FORCED_WRTHRU: forced write through (node down or flow control)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If this hint is cleared, when only one node is up,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_uncommit() will not work properly, and a second
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein failure could result in lost data.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is a node hint.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_NOCACHE: reuse cache blocks immediately instead of keeping
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in lru order.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This hint can be set on a device or per access.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_buf_handle_t *
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_alloc_handle(discon_cb, read_cb, write_cb)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*discon_cb)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*read_cb)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*write_cb)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The callbacks can be NULL if you do not want any callbacks.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Else, the callbacks will be stored in the handle, and will be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein called at specific points in the cache. (Its up to the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein callback to do what is necessary, including disconnecting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein from the channel)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Usage: for better performance, an application could allocate
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein a handle (or as many handles as is required) upfront and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein use it later on in the cache calls.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Not allocating and managing the handles would mean a new
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein handle will be allocated and freed during _sd_alloc_buf
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and _sd_freebuf.
065c66d9bf1c349600027bb50e3759a3736f73abMark Andrews_sd_free_handle(handle)
065c66d9bf1c349600027bb50e3759a3736f73abMark Andrews _sd_buf_handle_t *handle;
065c66d9bf1c349600027bb50e3759a3736f73abMark Andrews Only handles that are allocated through _sd_alloc_handle
065c66d9bf1c349600027bb50e3759a3736f73abMark Andrews should be freed with this call.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_alloc_buf (cd, fba_pos, fba_len, flag, handle_p)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_pos;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_len;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t **handle_p;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein cd = cache descriptor. Results in an error if this node does
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein not own this disk and the other node has not crashed.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (ie. requests must be routed to the correct node)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (see fault tolerant aspects discussed elsewhere)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_pos = disk position in multiples of 512 byte blocks.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_len = length in multiples of 512 bytes blocks.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (NOTE: This cannot exceed _SD_MAX_FBAS)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein flag = None, one or more of the following (described below):
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_RDBUF | SD_WRBUF | _SD_RDWRBUF | _SD_PINNABLE |
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_NOBLOCK | _SD_NOCACHE | _SD_WRTHRU
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein handle_p = (*handle_p = handle to be used for this call)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If *handle_p == NULL, a new handle will be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein allocated. _sd_free_buf will free up any handles
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein allocated in this fashion.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein NOTE: Handles allocated in this fashion will not have
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein any callbacks registered in them. As such,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_NOBLOCK flag along with a NULL handle would
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein result in the io being lost.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein return: Error number if > 0
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein possible errors:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein EINVAL if arguments are incorrect or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein cache not initialized or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein device not open.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein E2BIG if this request is a read and such a large
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein request cannot be currently satisfied. (break up
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the io or re-issue at a later point)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein EIO or any other errno that the driver might return.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Note: on error, the handle is not active,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and also is freed if *handle_p was NULL.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if 0 or less, status will be one of:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_DONE: buffer is ready, and ready to be used.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (with the blocks valid if _SD_RDBUF is set)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_PENDING:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein read callback, if one has been registered in the handle,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein will be called to complete this request.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_HIT: Same as _SD_DONE, read was satisfied by cache,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein or no blocking required for write buffer.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Note: _SD_RDBUF will issue the read if necessary.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_WRBUF allocates a network address to reflect to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein mirror node on _sd_write().
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein ~_SD_RDBUF allocates buffers but does NOT pre-read;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein use _sd_read() to fill in (portions) as req'd.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Note: flag == (_SD_RDBUF|_SD_WRTHRU|_SD_NOCACHE) will
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein clear valid bits (that are not dirty) thus read direct
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein from disk, without requiring a hash invalidate.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_write (handle, fba_pos, fba_len, flag)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t *handle;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_pos, fba_len;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein handle = handle previously allocated in allocate buf.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_pos and fba_len have to be within the allocated portion.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int flag. Flag: _SD_NOBLOCK | SD_WRTHRU
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Attempting to write to a handle that was not allocated for write
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein will return error (EINVAL)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns: errno if return > 0
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if 0 or less, return will be one of:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_PENDING: will be returned only if _SD_NOBLOCK is set AND
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein either the flag is _SD_WRTHRU or the other node is down,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein or the device/node is in write through mode
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_DONE: is returned if the block has been written to the disk.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_HIT: write block in cache..
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_read (handle, fba_pos, fba_len, flag)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t *handle;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_pos, fba_len;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein handle = handle previously allocated in allocate buf.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_pos and fba_len have to be within the allocated portion.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int flag. Flag: _SD_NOBLOCK
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns: errno if return > 0
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein error E2BIG if this request is big and cannot be currently
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein satisfied. (break up the io or re-issue at a later point)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if 0 or less, return will be one of:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_PENDING: will be returned only if _SD_NOBLOCK is set and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein we need to do an io.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_HIT: is returned if the blocks were satisfied by cache.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_DONE: some blocks were read from disk.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_uncommit(handle, fba_pos, fba_len, flag)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t *handle;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_pos, fba_len;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein handle = handle previously allocated in allocate buf.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein fba_pos and fba_len have to be within the allocated portion.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein flag: reserved for future use.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_uncommit could block and cannot be called from a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein "non-blocking" context.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (This is under review, from the ckd point of view)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns 0 (_SD_DONE) else errno;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_zero (handle, fba_pos, fba_len, flag)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t *handle;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_pos, fba_len;
a268fec7f54a89a0772a91da0511c8eae09e6157Mark Andrews handle = handle previously allocated in allocate buf.
1425217e5c3a2cbab7f8344e600e0c16047289ffMark Andrews fba_pos and fba_len have to be within the allocated portion.
a268fec7f54a89a0772a91da0511c8eae09e6157Mark Andrews zero the buffer described by the handle.
a268fec7f54a89a0772a91da0511c8eae09e6157Mark Andrews flag: _SD_NOBLOCK | _SD_WRTHRU
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The call commits data to disk.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This call has characteristics similar to _sd_write.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns: errno if return > 0
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if 0 or less, return will be one of:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_copy (handle1, handle2, fba_pos1, fba_pos2, fba_len)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t *handle1, handle2;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein int fba_pos1, fba_pos2, fba_len;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Copies relevant data from handle1 to handle2.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Useful for mirroring, remote dual copy, backup while open,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in-house tests, etc.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This call does not commit data to disk - you must explicitly
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein call _sd_write() on handle2 if that is what you want.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns: errno if return > 0:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein EIO - if sd module should do a generic bcopy
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein others - real error (passed to user)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if 0 or less, return will be:
c6d4f781529d2f28693546b25b2967d44ec89e60Mark Andrews _SD_DONE - sucess
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_free_buf(handle)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _sd_buf_handle_t *handle;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein handle = handle previously allocated in allocate buf.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns 0 (_SD_DONE) else errno;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_open(filename, flag)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein char *filename;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns a cache descriptor, or negative error number.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Typically use _sd_attach_cd(cd) before accessing the device.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Note: if devices is already open, it returns the same cache descriptor.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Currently there is no reference count; so one _sd_close() closes
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the cache descriptor (in all contexts).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_close(cd)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Similar to _sd_detach_cd below.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Note: intended to be called when terminating the cache; and not during
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein normal operation. No reference count (see above).
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Returns: 0 success, EIO.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_detach_cd(cd)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein re-reflect any pinned blocks to the other side,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein or wait for writes to flush; and invalidate that device's hash entries,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and relinquish device responsibility.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Returns: 0 success, EIO, EAGAIN.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_attach_cd(cd)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein If device has pinned blocks then scan for and re-pin those blocks
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (same idea as "node recovery" process, but per-device);
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and assert device responsibility.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_notify_all_pin(cd)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein rescan list of failed blocks and re-issue the pinned callback to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_register_pinned(func)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*func)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein callback (*func)(cd, fba_pos, fba_len) when disk write fails,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and _SD_PENDING was specified on alloc.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_register_unpinned(func)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*func)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein callback (*func)(cd, fba_pos, fba_len) when data previously pinned
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is successfully written to disk.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_register_down(func)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein void (*func)();
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein callback (*func)() when health monitor detects the other node went down.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_set_hint(cd, hint)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_clear_hint(cd, hint)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_get_cd_hint(cd, &hint)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_set_node_hint(hint)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_clear_node_hint(hint)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_get_node_hint(&hint)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein where hint is _SD_NOCACHE and _SD_WRTHRU. (Write through being synchronous
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein write and will be the default if the second node dies.)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein _SD_NOCACHE: hint indicating that the current access need not be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein cached for later consumption.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_discard_pinned(cd, fba_pos, fba_len)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein call from ckd into cache, called when data that was earlier
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein on pinned can be discarded from the cache.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns: 0 or error.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein (error = EINVAL if the discard could not be done)
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein(note: there is an inherent race between the unpinned callback and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein_sd_discard_pinned which could put the data on disk in an inconsistent
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinFailover support:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe Nodedown callback will be called, if one has been registered. This
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinwill happen as soon as the other node has been detected to have gone down,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinor when the cache is disabled on the other node.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinThe amount of time to for this callback to happen after the node goes down
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinis not deterministic.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAccess to a mirror node's devices is only valid from the point the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinnodedown callback is called till the other node is determined to be back
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinin operation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob AusteinAccess to mirror node's devices while recovery is in progress will
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinblock the access till the recovery is complete.