Bitmap handling (goal_bm)

This GOAL core module provides a function to allocate memory for a bit-field. Single bits of the bit-field can be taken from the bit-field by a function. The function can use the bit. If the bit is not more needed the function has to return the bit to the bit-field. If a bit is used, another function cannot take this bit from the bit-field. The bit-field must be allocated in state GOAL_FSA_INIT.

Figure: bitmap handling

Locking mechanisms are not implemented for the functions of this GOAL core module. If the locking of the bit-field is necessary, the locking must be done by the caller.
This GOAL core module provides no CM-variables and no command line interface.

GOAL files:
- goal_bm.[h,c]
example:
- not available

Implementation guidelines

Create a bit-field with a lock

Code: Create a bit-field with a lock

/* Create a handle to the bit-field. */
GOAL_BM_T *pFlags = NULL;

/* Create a handle for the lock to the bit-field. */
GOAL_LOCK_T *pLockFlags;

/* Create a binary lock to avoid multiple accesses to the bit-field. A binary lock has the value range [0,1]. */
GOAL_STATUS_T res; /* GOAL return value */

res = goal_lockCreate(GOAL_LOCK_BINARY, &pLockFlags, 0, 1, GOAL_ID_BM);

/* Allocate the memory for the bit-field in state GOAL_FSA_INIT for 16 bits. */
if (GOAL_RES_OK(res)) {
    res = goal_bmAlloc(&pFlags, 16);
}

Take a bit from the bit-field

Code: Take a bit from the bit-field

GOAL_STATUS_T res; /* GOAL return status */
uint32_t bitNum; /* number of the bit */

/* Set the lock. If the lock is not available, wait on the lock forever. */
res = goal_lockGet(pLockFlags, GOAL_LOCK_INFINITE);

/* Take the next available bit from the bit-field. */
if (GOAL_RES_OK(res)) { /* lock is set successful */
    res = goal_bmBitReq(pFlags, &bitNum);

    /* Reset the lock. */
    goal_lockPut(pLockFlags);
}

Return a bit to the bit-field

Code: Return a bit to the bit-field

GOAL_STATUS_T res; /* GOAL return status */

/* Set the lock. If the lock is not available, wait on the lock forever. */
res = goal_lockGet(pLockFlags, GOAL_LOCK_INFINITE);

/* Return the bit to the bit-field. */
if (GOAL_RES_OK(res)) { /* lock is set successful */
    res = goal_bmBitRel(pFlags, bitNum);

    /* Reset the lock. */
    goal_lockPut(pLockFlags);
}

1 Implementation guidelines