/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     os_MemoryBlock.h

  Copyright (C)2009 Nintendo Co., Ltd.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Rev: 24156 $
 *---------------------------------------------------------------------------*/

/*! @file
    @brief    OS からメモリを確保するための API の宣言

    :include nn/os.h
*/

#ifndef NN_OS_OS_MEMORYBLOCK_H_
#define NN_OS_OS_MEMORYBLOCK_H_

#include <nn/config.h>
#if NN_PLATFORM_HAS_MMU

#include <nn/types.h>
#include <nn/Handle.h>
#include <nn/svc.h>
#include <nn/os/CTR/os_MemoryConfig.h>
#include <nn/os/os_MemoryBlockBase.h>

#ifdef __cplusplus

#include <nn/util/util_NonCopyable.h>
#include <nn/os/os_SvcTypes.autogen.h>
#include <nn/util/util_Result.h>

namespace nn{ namespace os{

    class MemoryBlock;

    namespace detail
    {
        uptr AllocateFromMemoryBlockSpace(MemoryBlockBase* p, size_t s);
        void FreeToMemoryBlockSpace(MemoryBlockBase* p);
        void Switch(MemoryBlock* pTo, MemoryBlock* pFrom);

        bool IsMemoryBlockEnabled();
    }

    
/*!
    @brief ヒープ上の指定された領域内からメモリを確保するクラスです。

    このクラスを使用する前にあらかじめ @ref InitializeMemoryBlock を呼んでおく必要があります。

*/
class MemoryBlock : public MemoryBlockBase
{
public:
    /*!
        :overload notinit

        @brief オブジェクトを構築します。

               引数を指定しない場合は初期化を行いません。別途 @ref Initialize を呼び出す必要があります。
    */
    MemoryBlock() {}

    /*!
        :overload init

        @brief オブジェクトを構築し、メモリを確保します。

               内部で Initialize を呼び出すためメモリの確保も行います。

        @param[in] size 確保するメモリのサイズ
                        size は 4096 の倍数でなければなりません。
    */
    explicit MemoryBlock(size_t size) { Initialize(size); }

    /*!
        @brief メモリを確保します。

        InitializeMemoryBlock で指定した領域のうち、未使用の領域から
        size 分の領域を確保します。
    
        @param[in] size 確保するメモリのサイズ
                        size は 4096 の倍数でなければなりません。
    */
    void Initialize(size_t size);

    /*!
        @brief オブジェクトを破棄します。

        メモリの解放が行われていない場合は
        メモリの解放も行います。
    */
    ~MemoryBlock() { Finalize(); }

    /*!
        @brief メモリを解放します。
    */
    void Finalize();

    /*!
         @brief 読み込み専用属性を設定します。

         @param[in] readOnly 読み込み専用かどうか
    */
    void SetReadOnly(bool readOnly = true);

    static size_t GetPageAlignedSize(size_t size) { return (size + NN_OS_MEMORY_PAGE_SIZE - 1) & ~(NN_OS_MEMORY_PAGE_SIZE - 1); }
};

/*!--------------------------------------------------------------------------*
  @brief        MemoryBlock クラスおよび StackMemoryBlock クラスを
                使用できるようにします。

                MemoryBlock クラスおよび StackMemoryBlock クラスを
                構築する前に、これらのクラスが管理するメモリ領域を
                指定する必要があります。
                これらのクラスは
                @arg begin および @arg size で指定された領域から
                メモリを割り当てていきます。
    

  @param[in]    begin   MemoryBlock クラスおよび StackMemoryBlock クラスで
                        管理するメモリ領域の先頭アドレスを指定します。
  @param[in]    size    MemoryBlock クラスおよび StackMemoryBlock クラスで
                        管理するメモリ領域のサイズを指定します。
                        size は 4096 の倍数でなければなりません。

  @return       

 *---------------------------------------------------------------------------*/
void InitializeMemoryBlock(uptr begin, size_t size);


}} // namespace nn::os

#endif // __cplusplus

// 以下、C 用宣言

#include <nn/util/detail/util_CLibImpl.h>

/*!
  @addtogroup   nn_os               os
  @{
  
  @defgroup     nn_os_MemoryBlock_c       MemoryBlock (C)
  
  @brief        @ref nn::os::MemoryBlock の C インタフェースモジュールです。

  @{
*/

/*!
  @struct       nnosMemoryBlock
  @brief        メモリブロックを表す C の構造体です。

  @brief 対応するクラス @ref nn::os::MemoryBlock を参照してください。
*/
NN_UTIL_DETAIL_CLIBIMPL_DEFINE_BUFFER_CLASS(nnosMemoryBlock, nn::os::MemoryBlock, 20, u32);

/*!
  @brief 対応する C++ 関数 @ref nn::os::MemoryBlock::Initialize を参照してください。
*/
NN_EXTERN_C void nnosMemoryBlockAllocate(nnosMemoryBlock* p, size_t size);

/*!
  @brief 対応する C++ 関数 @ref nn::os::MemoryBlock::SetReadOnly を参照してください。
*/
NN_EXTERN_C void nnosMemoryBlockSetReadOnly(nnosMemoryBlock* p, bool readOnly);

/*
  @brief 対応する C++ 関数 @ref nn::os::MemoryBlock::Finalize を参照してください。
*/
NN_EXTERN_C void nnosMemoryBlockFree(nnosMemoryBlock* p);

/*!
  @brief 対応する C++ 関数 @ref nn::os::MemoryBlock::GetAddress を参照してください。
*/
NN_EXTERN_C uptr nnosMemoryBlockGetAddress(nnosMemoryBlock* p);

/*!
  @brief 対応する C++ 関数 @ref nn::os::MemoryBlock::GetSize を参照してください。
*/
NN_EXTERN_C size_t nnosMemoryBlockGetSize(nnosMemoryBlock* p);

/*!
  @brief 対応する C++ 関数 @ref nn::os::MemoryBlock::IsReadOnly を参照してください。
*/
NN_EXTERN_C bool nnosMemoryBlockIsReadOnly(nnosMemoryBlock* p);

/*!
  @}

  @}
*/

#endif  // if NN_PLATFORM_HAS_MMU
#endif /* NN_OS_OS_MEMORYBLOCK_H_ */