/*
   "kernel_string_pool.h"

   created by: grayspace aka J. Leveille
   for: UbixOS Project
   date: May 11, 2002

   purpose: to provide a mechanism for maintaining a pool of strings
            for use by the kernel without unnecessary waste of memory

   NOTEs:
      - for now only ASCII is supported
      - done quickly, pretty hacky

   TODO:
      - expand to support unicode
      - use huffman encoding instead
*/

#ifndef _KERNEL_STRING_POOL_H
#define _KERNEL_STRING_POOL_H

/* memory FORMAT of a 'KRNSTR': (quick and dirty for now)
   
   an 'ID' is used to indicate a string within the pool
   ----------------------------------------------------

   'ID' - [DWORD]:
      - 'num-words' - bits [0,7]
         - number of 'KRNWORD's in the string is 'num-words' + 1
      - bits [8,32]  BYTE offset inside pool where the 'KRNSTR'
                     (kernel string) is stored

   'KRNSTR's (kernel strings) are specified as an array of continuous BYTEs
   ------------------------------------------------------------------------

   'KRNSTR':
      - [KRNWORD] x 'num-words' (given by ID)

   'KRNWORD':
      - [BYTE] 'key1'

      - if key1 == [0,254]:
         - key1 is the index of the 'sub-string' in the pool

      - otherwise key1 is an escape sequence and implies:
         - [BYTE] 'key2'
         - [BYTE] 'key3'
         - the index of the 'sub-string' in the pool is key2*256 + key3 + 255

      - NOTE: the reason for using two extra 8-bit keys instead of a 16-bit
      value is in case we port to platform with data alignment exceptions
      and this stuff is left dormant and never changed

   - NOTE: a 'space' (0x20) is implied between each 'KRNWORD', therefore
   it is not currently possible to break encode string AB into substrings
   A & B if AB does not contain any spaces

   - a 'sub-string' is found by using the the index of the
   'sub-string' in the pool to get an offset into an array
   of continuous BYTEs via lookup

   'sub-string's are specified as an array of continuous BYTEs
   -----------------------------------------------------------

   - a 'sub-string' is as follows:

      - [BYTE] 'numchars' [0,255] -> [1,256]
      - [BYTE] x 'numchars' (the chars themselves)
   
   - WARNING: empty 'sub-string's are not allowed

*/

/* WARNING: it is *assumed* any 'ID' given to a kernel
            string pool function will be valid!!         */

/* structure for kernel string pool */
typedef struct tagKSTR_POOL
{
   /* pointer to where the kernel strings are stored */
   const BYTEg * p_krnstrs;

   /* pointer to where the sub strings are stored */
   const BYTEg * p_substrs;

   /* lookup table for substring offsets */
   const unsigned int * p_substr_off;
}
KSTR_POOL;

/* the reason for this structure format is so that a tool
   can be written which can generate a 'KSTR_POOL' from a configuration
   file and place it into a 'C' source and header file pair as static data */

// gets the substring indicated by 'id' from the pool 'p_ksp' into 'p_dst'
// - returns pointer to 'p_dst'
char * KSTR_POOL_GetString( KSTR_POOL * p_ksp, char * p_dst, DWORDg id );

#endif /* _KERNEL_STRING_POOL_H */