/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     os_StackMemoryBlock.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_STACKMEMORYBLOCK_H_
#define NN_OS_OS_STACKMEMORYBLOCK_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{

    namespace detail
    {
        void InitializeStackMemoryBlock();
    }

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

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

*/
class StackMemoryBlock : public MemoryBlockBase
{
private:
    uptr    m_MemoryAddress;

public:
    /*!
        :overload notinit

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

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

    /*!
        :overload init

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

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

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

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

        InitializeMemoryBlock で指定した領域のうち、未使用の領域から
        size 分の領域を確保します。

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

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

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

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

    /*!
        @brief 確保しているメモリ領域の終端アドレスを取得します。

        Thread::Start に StackMemoryBlock のインスタンスを
        直接渡すためのインターフェイスです。
    
        @return 確保しているメモリ領域の終端アドレスを返します。
    */
    uptr GetStackBottom() const { return GetAddress() + GetSize(); }
    
    /*!
        @brief 確保しているメモリ領域のサイズを取得します。

        Thread::Start に StackMemoryBlock のインスタンスを
        直接渡すためのインターフェイスです。

        @return 確保しているメモリ領域のサイズを返します。
    */
    size_t GetStackSize() const { return GetSize(); }
};

    namespace detail
    {
        void Switch(StackMemoryBlock* pTo, StackMemoryBlock* pFrom);
    }

}} // 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       nnosStackMemoryBlock
  @brief        スタックから確保したメモリブロックを表す C の構造体です。

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

NN_EXTERN_C void nnosStackMemoryBlockInitialize(nnosStackMemoryBlock* p);

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

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

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

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

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

/*!
  @}

  @}
*/

#endif  // if NN_PLATFORM_HAS_MMU
#endif /* NN_OS_OS_STACKMEMORYBLOCK_H_ */