The Kernel Kit: Miscellaneous Functions, Constants, and Defined Types

Miscellaneous Functions

debugger()

      void debugger(const char *string)

Throws the calling thread into the debugger. The string argument becomes the debugger's first utterance.

get_system_info()

      long get_system_info(system_info *info)

Returns information about the computer. The information is returned in info, a system_info structure.

is_computer_on()

      long is_computer_on(void)

Returns 1 if the computer is on. If the computer isn't on, the value returned by this function is undefined.

system_time()

      double system_time(void)

Returns the number of microseconds that have elapsed since the computer was booted.

Constants

Area Location Constants

Declared in: <kernel/OS.h>

Constant	Meaning
B_ANY_ADDRESS	Put the area anywhere
B_EXACT_ADDRESS	The area must start exactly at a given address
B_BASE_ADDRESS	The area can start anywhere above a given address
B_CLONE_ADDRESS	The clone must start at the same address as the original

These constants represent the different locations at which an area can be placed when it's created. They're used as values for the address arguments in create_area() and clone_area(). B_CLONE_ADDRESS can be passed to clone_area() only; the other three can be passed to either function.

See also: Areas

Area Lock Constants

Declared in: <kernel/OS.h>

Constant	Meaning
B_NO_LOCK	Never lock the area's pages
B_LAZY_LOCK	Lock pages as they're swapped in
B_FULL_LOCK	Lock all pages now

These constants represent an area's "locking scheme," the circumstances in which the area's underlying memory is locked into RAM. You set the locking scheme for an area by passing one of these constants to create_area()'s lock argument; the scheme can't be changed thereafter.

To query an area's locking scheme, retrieve its area_info structure (through get_area_info()) and look at the lock field.

See also: Areas

Area Protection Constants

Declared in: <kernel/OS.h>

Constant	Meaning
B_READ_AREA	The area can be read from
B_WRITE_AREA	The area can be written into

These constants represent the read and write protection that's enforced for an area. The constants are flags that can be added together and passed as the protection argument to create_area() and clone_area() . You can change an area's protection through the set_area_protection() function.

To query an area's protection, retrieve its area_info structure (through get_area_info()) and look at the protection field.

See also: Areas

CPU Count

Declared in: <kernel/OS.h>

Constant	Value
B_MAX_CPU_NUM	8

This constant gives the maximum number of CPUs that a single system can support. The cpu_count field of the system_info structure gives the number of CPUs that are actually on a given system. To retrieve this structure, call the get_system_info() function.

See also: get_system_info()

CPU Type Constant

Declared in: <kernel/OS.h>

Constant
B_CPU_PPC_601
B_CPU_PPC_603
B_CPU_PPC_603e
B_CPU_PPC_604
B_CPU_PPC_604e
B_CPU_PPC_686

These constants represent the different CPU chips that the BeBox has used/is using/might use. To discover which chip the local machine is using, looking in the cpu_type field of the system_info structure. To retrieve this structure, call the get_system_info() function.

See also: get_system_info()

File Name Length

Declared in: <kernel/OS.h>

Constant	Value
B_FILE_NAME_LENGTH	64

This constant gives the maximum length of the name of a file or directory.

Image Type Constants

Declared in: <kernel/image.h>

Constant	Meaning
B_APP_IMAGE	Application image
B_LIBRARY_IMAGE	Shared library image
B_ADD_ON_IMAGE	Add-on image
B_SYSTEM_IMAGE	System-defined image

The image type constants (type image_type ) enumerate the different images, or loadable compiled code, that you can create or otherwise find on the system. Of the four image types, you can't create B_SYSTEM_IMAGES; however, it's possible to run across a system- defined image if you retrieve all the image info structures for all teams (through the get_nth_image_info() function).

See also: Threads

Image Symbol Type Constants

Declared in: <kernel/OS.h>

Constant	Meaning
B_SYMBOL_TYPE_DATA	The symbol is a variable
B_SYMBOL_TYPE_TEXT	The symbol is a function

The image symbol type constants describe the nature of a particular image symbol. You retrieve symbol information from an image through the get_image_symbol().

See also: Threads

Operating System Doodad Name Length

Declared in: <kernel/OS.h>

Constant	Value
B_OS_NAME_LENGTH	32

This constant gives the maximum length of the name of a thread, semaphore, port, area, or other operating system bauble.

Page Size

Declared in: <kernel/OS.h>

Constant	Value
B_PAGE_SIZE	4096

The B_PAGE_SIZE constant gives the size, in bytes, of a page of RAM.

Port Message Count

Declared in: <kernel/OS.h>

Constant	Value
B_MAX_PORT_COUNT	128

This constant gives the maximum number of messages that a port can hold at a time. This value isn't applied automatically--you declare a port's message capacity when you create it.

To query a port's message capacity, retrieve its port_info structure (through the get_port_info() function) and look at the capacity field.

See also: Ports

Semaphore Control Flags

Declared in: <kernel/OS.h>

Acquire Flag	Meaning
B_TIMEOUT	Honor acquire_sem_etc()'s timeout argument.
B_CAN_INTERRUPT	The semaphore can be interrupted by a signal.
B_CHECK_PERMISSION	Make sure this isn't a system semaphore.

Release Flag	Meaning
B_DO_NOT_RESCHEDULE	Don't reschedule after the semaphore is released.

These are the flag values that can be passed to the acquire_sem_etc() and release_sem_etc() functions.

The timeout flag (B_TIMEOUT ) applies to all semaphore acquisitions: If, having set the B_TIMEOUT flag, your acquire_sem_etc() call blocks, the acquisition attempt will give up after some number of microseconds (as given in the function's timeout argument). If B_TIMEOUT isn't set, the acquisition can, potentially, block forever. The other two acquisition flags are used by device driver writers only. The meanings of these flags is given in the Device Kit chapter.

The B_DO_NOT_RESCHEDULE flag applies to the release_sem_etc() function. Normally, when a semaphore is released, the kernel immediately finds another thread to run, even if the releasing thread hasn't used up a full "schedule quantum" worth of CPU attention. By setting the B_DO_NOT_RESCHEDULE flag, you tell the scheduler to let the releasing thread run for its normally alloted amount of time.

Thread Priority Constants

Declared in: <kernel/OS.h>

Time-Sharing Priority	Value
B_LOW_PRIORITY	5
B_NORMAL_PRIORITY	10
B_DISPLAY_PRIORITY	15
B_URGENT_DISPLAY_PRIORITY	20

Real-Time Priority	Value
B_REAL_TIME_DISPLAY_PRIORITY	100
B_URGENT_PRIORITY	110
B_REAL_TIME_PRIORITY	120

These constants represent the thread priority levels. The higher a thread's priority value, the more attention it gets from the CPUs; the constants are listed here from lowest to highest priority.

There are two priority categories:

A time-sharing thread (a thread with a time-sharing priority value) is executed only if there are no real-time threads in the ready queue. In the absence of real-time threads, a time-sharing thread is elected to run once every "scheduler quantum" (currently, every three milliseconds). The higher the time-sharing thread's priority value, the greater the chance that it will be the next thread to run.

A real-time thread is executed as soon as it's ready. If more than one real-time thread is ready at the same time, the thread with the highet priority is executed first. The thread is allowed to run without being preempted (except by a real-time thread with a higher priority) until it blocks, snoozes, is suspended, or otherwise gives up its plea for attention.

You set a thread's priority when you spawn it (spawn_thread()); it can be changed thereafter through the set_thread_priority() function. Although you can set a thread priority to values other than those defined by the constants shown here, it's strongly suggested that you stick with the constants.

To query a thread's priority, look at the priority field of the thread's thread_info structure (which you can retrieve through get_thread_info()).

See also: Threads

Thread State Constants

Declared in: <kernel/OS.h>

Constant	Meaning
B_THREAD_RUNNING	The thread is currently receiving attention from a CPU.
B_THREAD_READY	The thread is waiting for its turn to run.
B_THREAD_RECEIVING	The thread is sitting in a receive_data() call.
B_THREAD_ASLEEP	The thread is sitting in a snooze() call.
B_THREAD_SUSPENDED	The thread has been suspended or is freshly-spawned.
B_THREAD_WAITING	The thread is waiting to acquire a semaphore.

These constants (type thread_state ) represent the various states that a thread can be in. You can't set a thread's state directly; the state changes as the result of the thread's sequence of operations.

You can query a thread's state by looking at the state field of its thread_info structure. To retrieve the structure, call get_thread_info(). Be aware, however, that a thread's state is extremely ephemeral; by the time you retrieve it, it may have changed.

See also: Threads

System Team ID

Declared in: <kernel/OS.h>

Constant	Meaning
B_SYSTEM_TEAM	The team_id of the kernel's team

The B_SYSTEM_TEAM constant identifies the kernel's team. You should only need to use this constant if you're bequeathing ownership of a port or semaphore to the kernel, an activity that's typically the province of driver writers.

Defined Types

area_id

Declared in: <kernel/OS.h>

      typedef long area_id

The area_id type uniquely identifies area.

See also: Areas

area_info

Declared in: <kernel/OS.h>

      typedef struct {
            area_id area;
            char name[B_OS_NAME_LENGTH];
            void *address;
            ulong size;
            ulong lock;
            ulong protection;
            team_id team;
            ulong  ram_size;
            ulong  copy_count;
            ulong  in_count;
            ulong  out_count;
         } area_info

The area_info structure holds information about a particular area. area_info structures are retrieved through the get_area_info() function. The structure's fields are:

• area is the area_id that identifies the area.

• name is the name that was assigned to the area when it was created or cloned.

• address is a pointer to the area's starting address. Keep in mind that this address is only meaningful to the application that created (or cloned) the area.

• size is the size of the area, in bytes.

• lock is a constant that represents the area's locking scheme. This will be one of B_FULL_LOCK, B_LAZY_LOCK, or B_NO_LOCK .

• protection specifies whether the area's memory can be read or written. It's a combination of B_READ_AREA and B_WRITE_AREA.

• team is the team_id of the thread that created or cloned this area.

Three of the final four fields (you can ignore the copy_count field) give information about the area that's useful in diagnosing system use:

See also: Areas

cpu_info

Declared in: <kernel/OS.h>

      typedef struct {
            double  active_time;
         } cpu_info

The cpu_info structure describes facets of a particular CPU. Currently, the structure contains only one field, active_time, that measures the amount of time, in microseconds, that the CPU has actively been working since the machine was last booted. One structure for each CPU is created and maintained by the system. An array of all such structures can be found in the cpu_infos field of the system_info structure. To retrieve a system_info structure, you call the get_system_info() function.

See also: system_info

image_info

Declared in: <kernel/image.h>

      typedef struct {
             long  volume;
             long  directory; 
             char  name[B_FILE_NAME_LENGTH]; 
            image_id id;
             void  *text;     
             long  text_size;    
             void  *data;     
             long  data_size;   
             image_type type;    
         } image_info

The image_info structure contains information about a specific image. The fields are:

The self-explanatory image_type constants are:

image_type

Declared in: <kernel/image.h>

      typedef enum { ... } image_type

The image_type type defines the different image types.

See also: Image Type Constants

machine_id

Declared in: <kernel/OS.h>

      typedef long machine_id[2]

The machine_id type encodes a 64-bit number that uniquely identifies a particular BeBox. To discover the machine id of the local machine, look in the id field of the system_info structure. To retrieve this structure, call the get_system_info() function.

See also: get_system_info()

port_id

Declared in: <kernel/OS.h>

      typedef long port_id

The port_id type uniquely identifies ports.

See also: Ports

port_info

Declared in: <kernel/OS.h>

      typedef struct port_info {
            port_id port;
            team_id team;
            char name[B_OS_NAME_LENGTH];
            long capacity;
            long queue_count;
            long total_count;
         } port_info

The port_info structure holds information about a particular port. It's fields are:

Note that the total_count number doesn't include the messages that are currently in the queue.

You retrieve a port_info structure through the get_port_info() function.

See also: Ports

sem_id

Declared in: <kernel/OS.h>

      typedef long sem_id

The sem_id type uniquely identifies semaphores.

See also: Semaphores

sem_info

Declared in: <kernel/OS.h>

      typedef struct sem_info {
            sem_id sem;
            team_id team;
            char name[B_OS_NAME_LENGTH];
            long count;
            thread_id latest_holder;
         } sem_info

The sem_info structure holds information about a given semaphore. The structure's fields are:

Note that the thread that's identified in the lastest_holder field may no longer be holding the semaphore--it may have since released the semaphore. The latest holder is simply the last thread to have called acquire_sem() (of whatever flavor) on this semaphore.

You retrieve a sem_info structure through the get_sem_info() function.

See also: Semaphores

system_info

Declared in: <kernel/OS.h>

      typedef struct {
            machine_id id;
            double boot_time;
            long cpu_count;
            long cpu_type;
            long cpu_revision;
            cpu_info cpu_infos[B_MAX_CPU_NUM];   
            double cpu_clock_speed;
            double bus_clock_speed;
            long max_pages;   
            long used_pages;
            long page_faults;
            long max_sems;         
            long used_sems;
            long max_ports;
            long used_ports;
            long max_threads;
            long used_threads;
            long max_teams;            
            long used_teams;
            long volume;               
            long directory;
            char name [B_FILE_NAME_LENGTH];
         } system_info

The system_info structure holds information about the machine and the state of the kernel. The structure's fields are:

The directory field is unusable: Directory ID numbers aren't visible through the present (public) means of file system access. But you can save the directory IDs that you collect now and trade them in for a higher draft pick next season.

You retrieve a system_info structure through the get_system_info() function.

See also: get_system_info()

team_id

Declared in: <kernel/OS.h>

      typedef long team_id

The team_id type uniquely identifies teams.

See also: Threads

team_info

Declared in: <kernel/OS.h>

      typedef struct {
            team_id team;
            long thread_count;
            long image_count;
            long area_count;
            thread_id debugger_nub_thread;
            port_id debugger_nub_port;
            long argc;
            char args[64];
         } team_info

The team_info structure holds information about a team. It's returned by the get_team_info() function. It's fields are:

• team is the team's ID number.

• thread_count, image_count, and area_count give the number of threads that have been spawned, images that have been loaded, and areas that have been created or cloned within this team.

• debugger_nub_thread and debugger_nub_port are used to communicate with the debugger. Unless you're designing your own debugger, you can ignore these fields.

• The argc field is the number of command line arguments that were used to launch the team; args is a copy of the first 64 characters from the command line invocation. If this team is an application that was launched through the user interface (by double-clicking, or by accepting a dropped icon), then argc is 1 and args is the name of the application's executable file.

See also: Threads

thread_entry

Declared in: <kernel/OS.h>

      typedef long (*thread_entry)(void *)

The thread_entry type is a function protocol for functions that are used as the entry points for new threads. You assign an entry function to a thread when you all spawn_thread() ; the function takes a thread_entry function as its first argument.

See also: Threads

thread_id

Declared in: <kernel/OS.h>

      typedef long thread_id

The thread_id type uniquely identifies threads.

See also: Threads

thread_info

Declared in: <kernel/OS.h>

      typedef struct {
            thread_id thread;
            team_id team;
            char name[B_OS_NAME_LENGTH];
            thread_state state;
            long priority;
            sem_id sem;
            double time;
            void *stack_base;
            void *stack_end;
         } thread_info

This structure holds information about a thread. It's returned by functions such as get_thread_info() . The fields are:

• thread. The thread_id number of the thread.

• team. The team_id of the thread's team.

• name. The name assigned to the thread.

• state. A constant that describes what the thread is currently doing.

• priority. A constant that represents the level of attention the thread gets.

• sem. If the thread is waiting to acquire a semaphore, this is the sem_id number of that semaphore. The sem field is only valid if the thread's state is B_THREAD_WAITING.

• time. The amount of active attention the thread has received from the CPUs, measured in microseconds.

• stack_base. A pointer to the first byte of memory in the thread's execution stack.

• stack_end. A pointer to the last byte of memory in the thread's execution stack.

See also: Threads

thread_state

Declared in: <kernel/OS.h>

      typedef enum { ... } thread_state

The thread_state type represents values that describe the various states that a thread can be in.

See also: Thread State Constants

The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.

Copyright © 1996 Be, Inc. All rights reserved.

Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

Last modified September 6, 1996.