xref: /src/sys/fs/udf/udf_readwrite.c

/* $NetBSD: udf_readwrite.c,v 1.14 2024/02/10 09:21:53 andvar Exp $ */

/*
 * Copyright (c) 2007, 2008 Reinoud Zandijk
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

#include <sys/cdefs.h>
#ifndef lint
__KERNEL_RCSID(0, "$NetBSD: udf_readwrite.c,v 1.14 2024/02/10 09:21:53 andvar Exp $");
#endif /* not lint */


#if defined(_KERNEL_OPT)
#include "opt_compat_netbsd.h"
#endif

#include <sys/param.h>
#include <sys/systm.h>
#include <sys/sysctl.h>
#include <sys/namei.h>
#include <sys/proc.h>
#include <sys/kernel.h>
#include <sys/vnode.h>
#include <miscfs/genfs/genfs_node.h>
#include <sys/mount.h>
#include <sys/buf.h>
#include <sys/file.h>
#include <sys/device.h>
#include <sys/disklabel.h>
#include <sys/ioctl.h>
#include <sys/malloc.h>
#include <sys/dirent.h>
#include <sys/stat.h>
#include <sys/conf.h>
#include <sys/kauth.h>
#include <sys/kthread.h>
#include <dev/clock_subr.h>

#include <fs/udf/ecma167-udf.h>
#include <fs/udf/udf_mount.h>

#include "udf.h"
#include "udf_subr.h"
#include "udf_bswap.h"


#define VTOI(vnode) ((struct udf_node *) vnode->v_data)

/* --------------------------------------------------------------------- */

void
udf_fixup_fid_block(uint8_t *blob, int lb_size,
	int rfix_pos, int max_rfix_pos, uint32_t lb_num)
{
	struct fileid_desc *fid;
	uint8_t *fid_pos;
	int fid_len, found;

	/* needs to be word aligned */
	KASSERT(rfix_pos % 4 == 0);

	/* first resync with the FID stream !!! */
	found = 0;
	while (rfix_pos + sizeof(struct desc_tag) <= max_rfix_pos) {
		fid_pos = blob + rfix_pos;
		fid = (struct fileid_desc *) fid_pos;
		if (udf_rw16(fid->tag.id) == TAGID_FID) {
			if (udf_check_tag((union dscrptr *) fid) == 0)
				found = 1;
		}
		if (found)
			break;
		/* try next location; can only be 4 bytes aligned */
		rfix_pos += 4;
	}

	/* walk over the fids */
	fid_pos = blob + rfix_pos;
	while (rfix_pos + sizeof(struct desc_tag) <= max_rfix_pos) {
		fid = (struct fileid_desc *) fid_pos;
		if (udf_rw16(fid->tag.id) != TAGID_FID) {
			/* end of FID stream; end of directory or currupted */
			break;
		}

		/* update sector number and recalculate checksum */
		fid->tag.tag_loc = udf_rw32(lb_num);
		udf_validate_tag_sum((union dscrptr *) fid);

		/* if the FID crosses the memory, we're done! */
		if (rfix_pos + UDF_FID_SIZE >= max_rfix_pos)
			break;

		fid_len = udf_fidsize(fid);
		fid_pos  += fid_len;
		rfix_pos += fid_len;
	}
}


void
udf_fixup_internal_extattr(uint8_t *blob, uint32_t lb_num)
{
	struct desc_tag        *tag;
	struct file_entry      *fe;
	struct extfile_entry   *efe;
	struct extattrhdr_desc *eahdr;
	int l_ea;

	/* get information from fe/efe */
	tag = (struct desc_tag *) blob;
	switch (udf_rw16(tag->id)) {
	case TAGID_FENTRY :
		fe = (struct file_entry *) blob;
		l_ea  = udf_rw32(fe->l_ea);
		eahdr = (struct extattrhdr_desc *) fe->data;
		break;
	case TAGID_EXTFENTRY :
		efe = (struct extfile_entry *) blob;
		l_ea  = udf_rw32(efe->l_ea);
		eahdr = (struct extattrhdr_desc *) efe->data;
		break;
	case TAGID_INDIRECTENTRY :
	case TAGID_ALLOCEXTENT :
	case TAGID_EXTATTR_HDR :
		return;
	default:
		panic("%s: passed bad tag\n", __func__);
	}

	/* something recorded here? (why am i called?) */
	if (l_ea == 0)
		return;

#if 0
	/* check extended attribute tag */
	/* TODO XXX what to do when we encounter an error here? */
	error = udf_check_tag(eahdr);
	if (error)
		return;	/* for now */
	if (udf_rw16(eahdr->tag.id) != TAGID_EXTATTR_HDR)
		return;	/* for now */
	error = udf_check_tag_payload(eahdr, sizeof(struct extattrhdr_desc));
	if (error)
		return; /* for now */
#endif

	DPRINTF(EXTATTR, ("node fixup: found %d bytes of extended attributes\n",
		l_ea));

	/* fixup eahdr tag */
	eahdr->tag.tag_loc = udf_rw32(lb_num);
	udf_validate_tag_and_crc_sums((union dscrptr *) eahdr);
}


void
udf_fixup_node_internals(struct udf_mount *ump, uint8_t *blob, int udf_c_type)
{
	struct desc_tag *tag, *sbm_tag;
	struct file_entry *fe;
	struct extfile_entry *efe;
	struct alloc_ext_entry *ext;
	uint32_t lb_size, lb_num;
	uint32_t intern_pos, max_intern_pos;
	int icbflags, addr_type, file_type, intern, has_fids, has_sbm, l_ea;

	lb_size = udf_rw32(ump->logical_vol->lb_size);
	/* if its not a node we're done */
	if (udf_c_type != UDF_C_NODE)
		return;

	/* NOTE this could also be done in write_internal */
	/* start of a descriptor */
	l_ea      = 0;
	has_fids  = 0;
	has_sbm   = 0;
	intern    = 0;
	file_type = 0;
	max_intern_pos = intern_pos = lb_num = 0;	/* shut up gcc! */

	tag = (struct desc_tag *) blob;
	switch (udf_rw16(tag->id)) {
	case TAGID_FENTRY :
		fe = (struct file_entry *) tag;
		l_ea = udf_rw32(fe->l_ea);
		icbflags  = udf_rw16(fe->icbtag.flags);
		addr_type = (icbflags & UDF_ICB_TAG_FLAGS_ALLOC_MASK);
		file_type = fe->icbtag.file_type;
		intern = (addr_type == UDF_ICB_INTERN_ALLOC);
		intern_pos  = UDF_FENTRY_SIZE + l_ea;
		max_intern_pos = intern_pos + udf_rw64(fe->inf_len);
		lb_num = udf_rw32(fe->tag.tag_loc);
		break;
	case TAGID_EXTFENTRY :
		efe = (struct extfile_entry *) tag;
		l_ea = udf_rw32(efe->l_ea);
		icbflags  = udf_rw16(efe->icbtag.flags);
		addr_type = (icbflags & UDF_ICB_TAG_FLAGS_ALLOC_MASK);
		file_type = efe->icbtag.file_type;
		intern = (addr_type == UDF_ICB_INTERN_ALLOC);
		intern_pos  = UDF_EXTFENTRY_SIZE + l_ea;
		max_intern_pos = intern_pos + udf_rw64(efe->inf_len);
		lb_num = udf_rw32(efe->tag.tag_loc);
		break;
	case TAGID_INDIRECTENTRY :
	case TAGID_EXTATTR_HDR :
		break;
	case TAGID_ALLOCEXTENT :
		/* force crclen to 8 for UDF version < 2.01 */
		ext = (struct alloc_ext_entry *) tag;
		if (udf_rw16(ump->logvol_info->min_udf_readver) <= 0x200)
			ext->tag.desc_crc_len = udf_rw16(8);
		break;
	default:
		panic("%s: passed bad tag\n", __func__);
		break;
	}

	/* determine what to fix if its internally recorded */
	if (intern) {
		has_fids = (file_type == UDF_ICB_FILETYPE_DIRECTORY) ||
			   (file_type == UDF_ICB_FILETYPE_STREAMDIR);
		has_sbm  = (file_type == UDF_ICB_FILETYPE_META_BITMAP);
	}

	/* fixup internal extended attributes if present */
	if (l_ea)
		udf_fixup_internal_extattr(blob, lb_num);

	/* fixup fids lb numbers */
	if (has_fids)
		udf_fixup_fid_block(blob, lb_size, intern_pos,
			max_intern_pos, lb_num);

	/* fixup space bitmap descriptor */
	if (has_sbm) {
		sbm_tag = (struct desc_tag *) (blob + intern_pos);
		sbm_tag->tag_loc = tag->tag_loc;
		udf_validate_tag_and_crc_sums((uint8_t *) sbm_tag);
	}

	udf_validate_tag_and_crc_sums(blob);
}

/* --------------------------------------------------------------------- */

/*
 * Set of generic descriptor readers and writers and their helper functions.
 * Descriptors inside `logical space' i.e. inside logically mapped partitions
 * can never be longer than one logical sector.
 *
 * NOTE that these functions *can* be used by the scheduler backends to read
 * node descriptors too.
 *
 * For reading, the size of allocated piece is returned in multiple of sector
 * size due to udf_calc_udf_malloc_size().
 */


/* SYNC reading of n blocks from specified sector */
int
udf_read_phys_sectors(struct udf_mount *ump, int what, void *blob,
	uint32_t start, uint32_t sectors)
{
	struct buf *buf, *nestbuf;
	uint32_t buf_offset;
	off_t lblkno, rblkno;
	int sector_size = ump->discinfo.sector_size;
	int blks = sector_size / DEV_BSIZE;
	int piece;
	int error;

	DPRINTF(READ, ("udf_intbreadn() : sectors = %d, sector_size = %d\n",
		sectors, sector_size));
	buf = getiobuf(ump->devvp, true);
	buf->b_flags    = B_READ;
	buf->b_cflags   = BC_BUSY;	/* needed? */
	buf->b_iodone   = NULL;
	buf->b_data     = blob;
	buf->b_bcount   = sectors * sector_size;
	buf->b_resid    = buf->b_bcount;
	buf->b_bufsize  = buf->b_bcount;
	buf->b_private  = NULL;	/* not needed yet */
	BIO_SETPRIO(buf, BPRIO_DEFAULT);
	buf->b_lblkno   = buf->b_blkno = buf->b_rawblkno = start * blks;
	buf->b_proc     = NULL;

	error = 0;
	buf_offset = 0;
	rblkno = start;
	lblkno = 0;
	while ((sectors > 0) && (error == 0)) {
		piece = MIN(MAXPHYS/sector_size, sectors);
		DPRINTF(READ, ("read in %d + %d\n", (uint32_t) rblkno, piece));

		nestbuf = getiobuf(NULL, true);
		nestiobuf_setup(buf, nestbuf, buf_offset, piece * sector_size);
		/* nestbuf is B_ASYNC */

		/* identify this nestbuf */
		nestbuf->b_lblkno   = lblkno;

		/* CD schedules on raw blkno */
		nestbuf->b_blkno      = rblkno * blks;
		nestbuf->b_proc       = NULL;
		nestbuf->b_rawblkno   = rblkno * blks;
		nestbuf->b_udf_c_type = what;

		udf_discstrat_queuebuf(ump, nestbuf);

		lblkno     += piece;
		rblkno     += piece;
		buf_offset += piece * sector_size;
		sectors    -= piece;
	}
	error = biowait(buf);
	putiobuf(buf);

	return error;
}


/* synchronous generic descriptor read */
int
udf_read_phys_dscr(struct udf_mount *ump, uint32_t sector,
		    struct malloc_type *mtype, union dscrptr **dstp)
{
	union dscrptr *dst, *new_dst;
	uint8_t *pos;
	int sectors, dscrlen;
	int i, error, sector_size;

	sector_size = ump->discinfo.sector_size;

	*dstp = dst = NULL;
	dscrlen = sector_size;

	/* read initial piece */
	dst = malloc(sector_size, mtype, M_WAITOK);
	error = udf_read_phys_sectors(ump, UDF_C_DSCR, dst, sector, 1);
	DPRINTFIF(DESCRIPTOR, error, ("read error (%d)\n", error));

	if (!error) {
		/* check if its a valid tag */
		error = udf_check_tag(dst);
		if (error) {
			/* check if its an empty block */
			pos = (uint8_t *) dst;
			for (i = 0; i < sector_size; i++, pos++) {
				if (*pos) break;
			}
			if (i == sector_size) {
				/* return no error but with no dscrptr */
				/* dispose first block */
				free(dst, mtype);
				return 0;
			}
		}
		/* calculate descriptor size */
		dscrlen = udf_tagsize(dst, sector_size);
	}
	DPRINTFIF(DESCRIPTOR, error, ("bad tag checksum\n"));

	if (!error && (dscrlen > sector_size)) {
		DPRINTF(DESCRIPTOR, ("multi block descriptor read\n"));
		/*
		 * Read the rest of descriptor. Since it is only used at mount
		 * time its overdone to define and use a specific udf_intbreadn
		 * for this alone.
		 */

		new_dst = realloc(dst, dscrlen, mtype, M_WAITOK);
		if (new_dst == NULL) {
			free(dst, mtype);
			return ENOMEM;
		}
		dst = new_dst;

		sectors = (dscrlen + sector_size -1) / sector_size;
		DPRINTF(DESCRIPTOR, ("dscrlen = %d (%d blk)\n", dscrlen, sectors));

		pos = (uint8_t *) dst + sector_size;
		error = udf_read_phys_sectors(ump, UDF_C_DSCR, pos,
				sector + 1, sectors-1);

		DPRINTFIF(DESCRIPTOR, error, ("read error on multi (%d)\n",
		    error));
	}
	if (!error) {
		error = udf_check_tag_payload(dst, dscrlen);
		DPRINTFIF(DESCRIPTOR, error, ("bad payload check sum\n"));
	}
	if (error && dst) {
		free(dst, mtype);
		dst = NULL;
	}
	*dstp = dst;

	return error;
}


static void
udf_write_phys_buf(struct udf_mount *ump, int what, struct buf *buf)
{
	struct buf *nestbuf;
	uint32_t buf_offset;
	off_t lblkno, rblkno;
	int sector_size = ump->discinfo.sector_size;
	int blks = sector_size / DEV_BSIZE;
	uint32_t sectors;
	int piece;
	int error;

	sectors = buf->b_bcount / sector_size;
	DPRINTF(WRITE, ("udf_intbwriten() : sectors = %d, sector_size = %d\n",
		sectors, sector_size));

	/* don't forget to increase pending count for the bwrite itself */
/* panic("NO WRITING\n"); */
	if (buf->b_vp) {
		mutex_enter(buf->b_vp->v_interlock);
		buf->b_vp->v_numoutput++;
		mutex_exit(buf->b_vp->v_interlock);
	}

	error = 0;
	buf_offset = 0;
	rblkno = buf->b_blkno / blks;
	lblkno = 0;
	while ((sectors > 0) && (error == 0)) {
		piece = MIN(MAXPHYS/sector_size, sectors);
		DPRINTF(WRITE, ("write out %d + %d\n",
		    (uint32_t) rblkno, piece));

		nestbuf = getiobuf(NULL, true);
		nestiobuf_setup(buf, nestbuf, buf_offset, piece * sector_size);
		/* nestbuf is B_ASYNC */

		/* identify this nestbuf */
		nestbuf->b_lblkno   = lblkno;

		/* CD schedules on raw blkno */
		nestbuf->b_blkno      = rblkno * blks;
		nestbuf->b_proc       = NULL;
		nestbuf->b_rawblkno   = rblkno * blks;
		nestbuf->b_udf_c_type = what;

		udf_discstrat_queuebuf(ump, nestbuf);

		lblkno     += piece;
		rblkno     += piece;
		buf_offset += piece * sector_size;
		sectors    -= piece;
	}
}


/* SYNC writing of n blocks from specified sector */
int
udf_write_phys_sectors(struct udf_mount *ump, int what, void *blob,
	uint32_t start, uint32_t sectors)
{
	struct vnode *vp;
	struct buf *buf;
	int sector_size = ump->discinfo.sector_size;
	int blks = sector_size / DEV_BSIZE;
	int error;

	/* get transfer buffer */
	vp = ump->devvp;
	buf = getiobuf(vp, true);
	buf->b_flags    = B_WRITE;
	buf->b_cflags   = BC_BUSY;	/* needed? */
	buf->b_iodone   = NULL;
	buf->b_data     = blob;
	buf->b_bcount   = sectors * sector_size;
	buf->b_resid    = buf->b_bcount;
	buf->b_bufsize  = buf->b_bcount;
	buf->b_private  = NULL;	/* not needed yet */
	BIO_SETPRIO(buf, BPRIO_DEFAULT);
	buf->b_lblkno   = buf->b_blkno = buf->b_rawblkno = start * blks;
	buf->b_proc     = NULL;

	/* do the write, wait and return error */
	udf_write_phys_buf(ump, what, buf);
	error = biowait(buf);
	putiobuf(buf);

	return error;
}


/* synchronous generic descriptor write */
int
udf_write_phys_dscr_sync(struct udf_mount *ump, struct udf_node *udf_node, int what,
		     union dscrptr *dscr, uint32_t sector, uint32_t logsector)
{
	struct vnode *vp;
	struct buf *buf;
	int sector_size = ump->discinfo.sector_size;
	int blks = sector_size / DEV_BSIZE;
	int dscrlen;
	int error;

	/* set sector number in the descriptor and validate */
	dscr->tag.tag_loc = udf_rw32(logsector);
	udf_validate_tag_and_crc_sums(dscr);

	/* calculate descriptor size */
	dscrlen = udf_tagsize(dscr, sector_size);

	/* get transfer buffer */
	vp = udf_node ? udf_node->vnode : ump->devvp;
	buf = getiobuf(vp, true);
	buf->b_flags    = B_WRITE;
	buf->b_cflags   = BC_BUSY;	/* needed? */
	buf->b_iodone   = NULL;
	buf->b_data     = (void *) dscr;
	buf->b_bcount   = dscrlen;
	buf->b_resid    = buf->b_bcount;
	buf->b_bufsize  = buf->b_bcount;
	buf->b_private  = NULL;	/* not needed yet */
	BIO_SETPRIO(buf, BPRIO_DEFAULT);
	buf->b_lblkno   = buf->b_blkno = buf->b_rawblkno = sector * blks;
	buf->b_proc     = NULL;

	/* do the write, wait and return error */
	udf_write_phys_buf(ump, what, buf);
	error = biowait(buf);
	putiobuf(buf);

	return error;
}


/* asynchronous generic descriptor write */
int
udf_write_phys_dscr_async(struct udf_mount *ump, struct udf_node *udf_node,
		      int what, union dscrptr *dscr,
		      uint32_t sector, uint32_t logsector,
		      void (*dscrwr_callback)(struct buf *))
{
	struct vnode *vp;
	struct buf *buf;
	int dscrlen;
	int sector_size = ump->discinfo.sector_size;
	int blks = sector_size / DEV_BSIZE;

	KASSERT(dscrwr_callback);
	DPRINTF(NODE, ("udf_write_phys_dscr_async() called\n"));

	/* set sector number in the descriptor and validate */
	dscr->tag.tag_loc = udf_rw32(logsector);
	udf_validate_tag_and_crc_sums(dscr);

	/* calculate descriptor size */
	dscrlen = udf_tagsize(dscr, sector_size);

	/* get transfer buffer */
	vp = udf_node ? udf_node->vnode : ump->devvp;
	buf = getiobuf(vp, true);
	buf->b_flags    = B_WRITE; // | B_ASYNC;
	buf->b_cflags   = BC_BUSY;
	buf->b_iodone	= dscrwr_callback;
	buf->b_data     = dscr;
	buf->b_bcount   = dscrlen;
	buf->b_resid    = buf->b_bcount;
	buf->b_bufsize  = buf->b_bcount;
	buf->b_private  = NULL;	/* not needed yet */
	BIO_SETPRIO(buf, BPRIO_DEFAULT);
	buf->b_lblkno   = buf->b_blkno = buf->b_rawblkno = sector * blks;
	buf->b_proc     = NULL;

	/* do the write and return no error */
	udf_write_phys_buf(ump, what, buf);
	return 0;
}

/* --------------------------------------------------------------------- */

/* disc strategy dispatchers */

int
udf_create_logvol_dscr(struct udf_mount *ump, struct udf_node *udf_node, struct long_ad *icb,
	union dscrptr **dscrptr)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;
	int error;

	KASSERT(strategy);
	args.ump  = ump;
	args.udf_node = udf_node;
	args.icb  = icb;
	args.dscr = NULL;

	error = (strategy->create_logvol_dscr)(&args);
	*dscrptr = args.dscr;

	return error;
}


void
udf_free_logvol_dscr(struct udf_mount *ump, struct long_ad *icb,
	void *dscr)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;

	KASSERT(strategy);
	args.ump  = ump;
	args.icb  = icb;
	args.dscr = dscr;

	(strategy->free_logvol_dscr)(&args);
}


int
udf_read_logvol_dscr(struct udf_mount *ump, struct long_ad *icb,
	union dscrptr **dscrptr)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;
	int error;

	KASSERT(strategy);
	args.ump  = ump;
	args.icb  = icb;
	args.dscr = NULL;

	error = (strategy->read_logvol_dscr)(&args);
	*dscrptr = args.dscr;

	return error;
}


int
udf_write_logvol_dscr(struct udf_node *udf_node, union dscrptr *dscr,
	struct long_ad *icb, int waitfor)
{
	struct udf_strategy *strategy = udf_node->ump->strategy;
	struct udf_strat_args args;
	int error;

	KASSERT(strategy);
	args.ump      = udf_node->ump;
	args.udf_node = udf_node;
	args.icb      = icb;
	args.dscr     = dscr;
	args.waitfor  = waitfor;

	error = (strategy->write_logvol_dscr)(&args);
	return error;
}


void
udf_discstrat_queuebuf(struct udf_mount *ump, struct buf *nestbuf)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;

	KASSERT(strategy);
	args.ump = ump;
	args.nestbuf = nestbuf;

	(strategy->queuebuf)(&args);
}


void
udf_synchronise_caches(struct udf_mount *ump)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;

	KASSERT(strategy);
	args.ump = ump;

	(strategy->sync_caches)(&args);
}


void
udf_discstrat_init(struct udf_mount *ump)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;

	KASSERT(strategy);
	args.ump = ump;
	(strategy->discstrat_init)(&args);
}


void udf_discstrat_finish(struct udf_mount *ump)
{
	struct udf_strategy *strategy = ump->strategy;
	struct udf_strat_args args;

	/* strategy might not have been set, so ignore if not set */
	if (strategy) {
		args.ump = ump;
		(strategy->discstrat_finish)(&args);
	}
}

/* --------------------------------------------------------------------- */