/*
 * Copyright (c) 2026, Chloe M.
 * Provided under the BSD-3 clause.
 *
 * Description: Virtual address descriptor management
 * Author:      Chloe M.
 */

#ifndef _MM_VAD_H_
#define _MM_VAD_H_ 1

#include <ptapi/status.h>
#include <ptdef.h>
#include <mm/vm.h>
#include <tree.h>

/*
 * A virtual address descriptor represents a single page
 * of memory that can be allocated.
 *
 * @Range:      Virtual memory range this covers
 * @TreeLink:   Red-black tree link
 */
typedef struct _MM_VAD {
    MM_RANGE Range;
    RB_ENTRY(_MM_VAD) TreeLink;
} MM_VAD;

/*
 * A virtual address descriptor tree lists a collection
 * of virtual address descriptors in an ordered manner.
 *
 * @Head:       Head of the red-black tree
 * @Elements    Number of elements in red-black tree
 */
typedef struct {
    RB_HEAD(VadTree, _MM_VAD) Head;
    USIZE Elements;
} MM_VAD_TREE;

/*
 * Initialize a virtual address descriptor tree
 *
 * @Tree: Tree to initialize
 */
VOID MmVadTreeInit(MM_VAD_TREE *Tree);

/*
 * Insert a virtual address descriptor into a virtual address
 * descriptor tree.
 *
 * @Tree:  VAD tree to be inserted into
 * @Vad:   VAD to insert
 */
PT_STATUS MmVadTreeInsert(MM_VAD_TREE *Tree, MM_VAD *Vad);

/*
 * Allocate a number of virtual address descriptors from a
 * VAD tree.
 *
 * @Tree:       VAD tree to allocate from
 * @PageCount:  Page count
 *
 * Returns NULL on failure / out of memory
 */
MM_VAD *MmVadTreeAllocate(MM_VAD_TREE *Tree, USIZE PageCount);

#endif  /* !_MM_VAD_H_ */