/*
*********************************************************************************************************
*                                                uC/OS-II
*                                          The Real-Time Kernel
*                                            MEMORY MANAGEMENT
*
*                          (c) Copyright 1992-2002, Jean J. Labrosse, Weston, FL
*                                           All Rights Reserved
*
* File : OS_MEM.C
* By   : Jean J. Labrosse
*********************************************************************************************************
*/

#ifndef  OS_MASTER_FILE
#include "includes.h"
#endif

#if (OS_MEM_EN > 0) && (OS_MAX_MEM_PART > 0)//允許包含內(nèi)在管理代碼且內(nèi)在分區(qū)數(shù)大于0
/*
*********************************************************************************************************
*                                        CREATE A MEMORY PARTITION
*
* Description : Create a fixed-sized memory partition that will be managed by uC/OS-II.
*
* Arguments   : addr     is the starting address of the memory partition
*
*               nblks    is the number of memory blocks to create from the partition.
*
*               blksize  is the size (in bytes) of each block in the memory partition.
*
*               err      is a pointer to a variable containing an error message which will be set by
*                        this function to either:
*
*                        OS_NO_ERR            if the memory partition has been created correctly.
*                        OS_MEM_INVALID_ADDR  you are specifying an invalid address for the memory 
*                                             storage of the partition.
*                        OS_MEM_INVALID_PART  no free partitions available
*                        OS_MEM_INVALID_BLKS  user specified an invalid number of blocks (must be >= 2)
*                        OS_MEM_INVALID_SIZE  user specified an invalid block size
*                                             (must be greater than the size of a pointer)
* Returns    : != (OS_MEM *)0  is the partition was created
*              == (OS_MEM *)0  if the partition was not created because of invalid arguments or, no
*                              free partition is available.
*********************************************************************************************************
*/
/*
*********************************************************************************************************
                                                           建立一個內(nèi)存分區(qū)
描述：建立一個可由ucosII管理的大小固定的內(nèi)存塊
參數(shù)：addr ：內(nèi)存分區(qū)的起始地址
          nblks：從分割區(qū)中要建立內(nèi)在塊的數(shù)目
          blksize：內(nèi)在分割區(qū)中每塊內(nèi)存的大小（用字節(jié)表示）
           err：是由下列函數(shù)決定的，包含錯誤信息的可變指針：
               OS_NO_ERR：如果內(nèi)存塊建立正確
               OS_MEM_INVALID_ADDR：你為分割區(qū)的內(nèi)在空間指定了不可用地址
               OS_MEM_INVALID_PART：沒有多余的區(qū)域了。
               OS_MEM_INVALID_BLKS：用戶指定分割數(shù)目不合法（必須大于等于2）
               OS_MEM_INVALID_SIZE：用戶指定了非法的內(nèi)存塊大小（必須大于指針的大小）
返回： != (OS_MEM *)0：分區(qū)已經(jīng)建立
            == (OS_MEM *)0：因為非法參數(shù)或者沒有空余塊而沒有建立分區(qū)

*********************************************************************************************************
*/


OS_MEM  *OSMemCreate (void *addr, INT32U nblks, INT32U blksize, INT8U *err)
{
#if OS_CRITICAL_METHOD == 3                           /* Allocate storage for CPU status register      */
    OS_CPU_SR  cpu_sr;//typedef unsigned int OS_CPU_SR
#endif    
    OS_MEM    *pmem;//內(nèi)存控制塊數(shù)據(jù)結(jié)構(gòu)
    INT8U     *pblk;
    void     **plink;//指向指針的指針
    INT32U     i;


#if OS_ARG_CHK_EN > 0//允許參數(shù)檢驗
    if (addr == (void *)0) {                          /* Must pass a valid address for the memory part. */
        *err = OS_MEM_INVALID_ADDR;//要為內(nèi)存塊建立一個合法地址，即地址要有效
        return ((OS_MEM *)0);//返回
    }
    if (nblks < 2) {                                  /* Must have at least 2 blocks per partition      */
        *err = OS_MEM_INVALID_BLKS;//內(nèi)存分塊太少了，必須最小兩塊
        return ((OS_MEM *)0);
    }
    if (blksize < sizeof(void *)) {                   /* Must contain space for at least a pointer      */
        *err = OS_MEM_INVALID_SIZE;//每個內(nèi)存塊至少要容不得得下一個指針，因為
        //同一分區(qū)中的所有空余內(nèi)在塊是由指針鏈串聯(lián)起來的。
        return ((OS_MEM *)0);
    }
#endif
    OS_ENTER_CRITICAL();
    pmem = OSMemFreeList;                             /* Get next free memory partition                */
	//從系統(tǒng)中的空余內(nèi)存控制塊鏈表中取得一個內(nèi)存控制塊，該項內(nèi)存
	//控制塊中包含相應(yīng)內(nèi)在分區(qū)的運(yùn)行狀態(tài)信息。
    if (OSMemFreeList != (OS_MEM *)0) {               /* See if pool of free partitions was empty      */
		//內(nèi)存分區(qū)的空鏈表指針是否為空，如不為空，
        OSMemFreeList = (OS_MEM *)OSMemFreeList->OSMemFreeList;//這是什么意思？將空余塊賦給空余內(nèi)存塊？
    }
    OS_EXIT_CRITICAL();
    if (pmem == (OS_MEM *)0) {                        /* See if we have a memory partition             */
        *err = OS_MEM_INVALID_PART;//看是否有多余的內(nèi)存控制塊
        return ((OS_MEM *)0);
    }
    plink = (void **)addr;             /* Create linked list of free memory blocks  當(dāng)條件都滿足時    */
    pblk  = (INT8U *)addr + blksize;//所要建立的內(nèi)存分區(qū)內(nèi)的所有內(nèi)存塊鏈按成一個單向
    //鏈表。因為在單向鏈表中插入和刪除元素都是從鏈表的頂端開始向下執(zhí)行的。
    for (i = 0; i < (nblks - 1); i++) {
        *plink = (void *)pblk;
        plink  = (void **)pblk;//這兩句為什么要這么寫？
        pblk   = pblk + blksize;//這個我懂。
    }
    *plink              = (void *)0;                  /* Last memory block points to NULL              */
	//單向鏈表從上分到下，最后一塊指向零。
	//下面這幾句是保存相關(guān)的信息
    pmem->OSMemAddr     = addr;                       /* Store start address of memory partition       */
    pmem->OSMemFreeList = addr;                       /* Initialize pointer to pool of free blocks     */
    pmem->OSMemNFree    = nblks;                      /* Store number of free blocks in MCB            */
    pmem->OSMemNBlks    = nblks;
    pmem->OSMemBlkSize  = blksize;                    /* Store block size of each memory blocks        */
	//保存每一塊內(nèi)存塊的大小
    *err                = OS_NO_ERR;//沒有錯誤
    return (pmem);//操作完成后，返回指向該內(nèi)存控制塊的指針。該指針在以后對該
    //內(nèi)存分區(qū)的操作中使用。
}
/*$PAGE*/
/*
*********************************************************************************************************
*                                          GET A MEMORY BLOCK
*
* Description : Get a memory block from a partition
*
* Arguments   : pmem    is a pointer to the memory partition control block
*
*               err     is a pointer to a variable containing an error message which will be set by this
*                       function to either:
*
*                       OS_NO_ERR           if the memory partition has been created correctly.
*                       OS_MEM_NO_FREE_BLKS if there are no more free memory blocks to allocate to caller
*                       OS_MEM_INVALID_PMEM if you passed a NULL pointer for 'pmem'
*
* Returns     : A pointer to a memory block if no error is detected
*               A pointer to NULL if an error is detected
*********************************************************************************************************
*/
 /*
 *********************************************************************************************************
                                             分配內(nèi)存塊
 描述：從分割區(qū)得到一塊內(nèi)存塊
 參數(shù)：pmem：一個指向內(nèi)存分割控制塊的指針
			err：可以包含以下錯誤信息的指針：
					OS_NO_ERR：如果內(nèi)存分割正確創(chuàng)建
					OS_MEM_NO_FREE_BLKS：沒有多余的內(nèi)存控制塊調(diào)用
					OS_MEM_INVALID_PMEM：如果傳一個空指針給"pmem"
 
 返回：如果無錯誤則返回一個指向內(nèi)存控制塊的指針，如果有錯誤返回一個空指針	
備注：應(yīng)用程序應(yīng)該知道分配內(nèi)在大小，并在使用的時候不能超過它的大小
應(yīng)用程序不用的時候，應(yīng)當(dāng)將其釋放，重新回到相應(yīng)的相應(yīng)的內(nèi)在分區(qū)中
 *********************************************************************************************************
*/


void  *OSMemGet (OS_MEM *pmem, INT8U *err)
{//傳遞指針pmem，它指向希望從中分配到的內(nèi)存塊的內(nèi)存分區(qū)
#if OS_CRITICAL_METHOD == 3                           /* Allocate storage for CPU status register      */
    OS_CPU_SR  cpu_sr;
#endif    
    void      *pblk;


#if OS_ARG_CHK_EN > 0
    if (pmem == (OS_MEM *)0) {                        /* Must point to a valid memory partition         */
        *err = OS_MEM_INVALID_PMEM;//內(nèi)存塊地址為零，不可用
        return ((OS_MEM *)0);
    }
#endif
    OS_ENTER_CRITICAL();
    if (pmem->OSMemNFree > 0) {                       /* See if there are any free memory blocks       */
		//看是不是有多余的內(nèi)存塊
        pblk                = pmem->OSMemFreeList;    /* Yes, point to next free memory block          */
		//有多余的，指向向下一個內(nèi)存塊，即刪除第一塊
        pmem->OSMemFreeList = *(void **)pblk;         /*      Adjust pointer to new free list          */
       //調(diào)整新的鏈表指針
        pmem->OSMemNFree--;                           /*      One less memory block in this partition  */
	   //塊數(shù)減一
        OS_EXIT_CRITICAL();
        *err = OS_NO_ERR;                             /*      No error                                 */
		//沒有錯誤
        return (pblk);                                /*      Return memory block to caller            */
		//返回得到的內(nèi)存塊
    }
    OS_EXIT_CRITICAL();
    *err = OS_MEM_NO_FREE_BLKS;                       /* No,  Notify caller of empty memory partition  */
	//沒有多余的，
    return ((void *)0);                               /*      Return NULL pointer to caller            */
}
/*$PAGE*/
/*
*********************************************************************************************************