rdsinit(1)

📦 version 1.28, in fedora 43, fedora 44

✨ NAME ✨

rdsinit — the RDS heap initialization utility. short, sweet, iconic. 💅

🎀 SYNOPSIS 🎀

rdsinit log data_seg

rdsinit log data_seg datalen saddr hlen slen nl chunk

rdsinit -f log data_seg datalen saddr hlen slen nl chunk

🦋 DESCRIPTION 🦋

okay so bestie, rdsinit is a utility that constructs an initialized RDS heap inside an RVM segment. Its whole purpose in life is to build a structure that can then be loaded by rds_load_heap. setup queen behavior, fr fr. 👑

There are three different ways to use rdsinit, and they are not all equal:

  1. General users are expected to use the first two interactive modes, where you supply parameters for the rds heap either interactively or as command line arguments.
  2. In both of those cases, you'll be asked interactively to confirm your choice of parameters before rdsinit goes ahead and makes any permanent change. These are the preferred modes of using rdsinit. 💖
  3. Script writers, though, may prefer to supply all the parameters on the command line with no confirmation required for those parameters. That's what the third mode is for: you just add the extra switch -f (firm) on the command line.

In any case, two command-line parameters are always required: log and data_seg.

  • log — the name of the RVM log, which must have previously been initialized by rvmutl.
  • data_seg — the name of the data segment that will be initialized with an RDS heap.

If either one is missing, a command line error gets printed. If the log has not been initialized, an RVM error will result. A short message indicating RVM initialization succeeded is then printed. And btw, both the log and the data segment can be regular files or raw partitions. flexible, we love that. 🌈

🔢 the six numeric parameters 🔢

After the name of log and the data segment, there are six other numeric parameters required. Here's the quick rundown — they get explained one by one in the paragraphs after, no skipping:

  • datalen — Length of data segment
  • saddr — Starting address of rvm
  • hlen — Heap region length
  • slen — Static region length
  • nl — Number of lists of free block
  • chunk — Chunk size

While entering these six numeric parameters, whether on the command line or via the interactive prompt, you may use numeric numbers in hexadecimal, decimal, or even octal notation. Here's the tea:

  • Hexadecimal numbers are preceded by Ox
  • Decimal numbers are preceded by nothing
  • Octal numbers are preceded by 0
⚠️ Special note for long time rdsinit user: the old rdsinit automatically assumed the saddr, hlen and slen parameters supplied on command lines are in hexadecimal and did not require the prefix 0x. This is no longer true with this version of rdsinit. adjust or perish, bestie. 😭

📏 datalen 📏

You specify the length of the data segment with the parameter datalen. Again — the old version of rdsinit did not require this parameter if the data segment was a regular file and it existed already at the time of running rdsinit. That special case is eliminated. Length of data segment must be supplied in all circumstances. no exceptions, periodt. 💅

📍 saddr 📍

Starting address of rvm, aka saddr, is where the heap and static region will be mapped into virtual memory.

  • The heap region is located right at the starting address.
  • The static region is located at starting address plus heap region length.

You may need some knowledge of the overall layout of the virtual memory used by the system before you can make the right choice of starting address. For example:

  • The starting address of rvm must be much larger than the largest possible break point of your application.
  • It should not be in conflict with other uses of virtual memory (such as use by shared libraries).
  • It must also be on a page boundary.

In CMU, we use 0x20000000 (536870912) with Linux and BSD44, or 0x70000000 (1879048192) with Mach. It is possible to choose other values, but you have to choose them carefully. choose wisely, bestie. 🧚

📐 hlen and slen 📐

Length of regions of heap and static are specified by the parameter hlen and slen respectively. Both rules, no cap:

  • They both must be an integral multiple of pagesize of the system.
  • The combined length of the two regions must be smaller than the length of the data segment minus one extra page.
🚨 Note that the above three parameters: saddr, hlen, slen, are permanent. They can't be changed without re-initizing (and brain-wiping) the data segment. that's not a vibe check you want to fail, fr. 💀

🗂️ nl and chunk 🗂️

The next two parameters, nl and chunk, are related to the underlying structure of management of the heap. RDS uses the Quick Fit method for heap allocation. In this method, free blocks are maintained by a number of free lists, each list for one particular size of free blocks. Specifically, there will be nl free lists, and each of them will have free blocks of size 1..nl chunk respectively. slay. ✨

Rules of the game:

  • Chunk size must be an integral multiple of sizeof(char *), and be at least RDS_MIN_CHUNK_SIZE.
  • Number of lists must be at least RDS_MIN_FREE_LISTS.
  • For example, a reasonable choice is to have 100 free list with chunk size 32 bytes. 💖

✅ the confirmation moment ✅

Once all the parameters are chosen, rdsinit will ask you for confirmation before it goes ahead and makes a permanent change on the log and data segment. Note in the following example that those numerical arguments are presented in both hexadecimal and decimal (in bracket). It is safe to quit at this point and no permanent changes will be made. phew. 🫶

The following parameters are chosen:
   length of data segment:    0xf5000 (   1003520)
  starting address of rvm: 0x20000000 ( 536870912)
                 heap len:    0xf0000 (    983040)
               static len:     0x4000 (     16384)
                   nlists:       0x64 (       100)
               chunk size:       0x20 (        32)
Do you agree with these parameters ? (y|n|q) y

And if you supplied the -f (firm) switch on the command line, this last confirmation will not show up. no take-backs, no safety net. 😌

🌈 SEE ALSO 🌈

  • rds_init_heap (3)
  • rds_load_heap (3)
  • rds_zap_heap (3)
  • rvm_create_segment (3)
  • rvm_load_segment (3)
  • rvmutl (1)

👑 AUTHOR 👑

  • David C. Steere, created man page
  • Yui W. Lee, modified (Sept 1997)

okay that's the whole thing bestie, go init that heap 💖✨ this came out of the General Commands Manual, page rdsinit(1), and it's giving modified Sept 1997 energy. mwah. 🎀🦋

📦 where this page comes from