Subversion Repositories HelenOS

BDSH - The Brain Dead Shell | Design Documentation

BDSH - The Brain Dead Shell | Design Documentation

--------------------------------------------------

--------------------------------------------------

Overview:

Overview:

=========

=========

BDSH was written as a drop in command line interface for HelenOS to permit

BDSH was written as a drop in command line interface for HelenOS to permit

interactive access to persistent file systems in development. BDSH was

interactive access to persistent file systems in development. BDSH was

written from scratch with a very limited userspace standard C library in

written from scratch with a very limited userspace standard C library in

mind. Much like the popular Busybox program, BDSH provides a very limited

mind. Much like the popular Busybox program, BDSH provides a very limited

shell with limited common UNIX creature comforts built in.

shell with limited common UNIX creature comforts built in.

Porting Busybox (and by extension ASH) would have taken much longer to

Porting Busybox (and by extension ASH) would have taken much longer to

complete, much less make stable due to stark differences between Linux and

complete, much less make stable due to stark differences between Linux and

Spartan with regards to IPC, term I/O and process creation. BDSH was written

Spartan with regards to IPC, term I/O and process creation. BDSH was written

and made stable within the space of less than 30 days.

and made stable within the space of less than 30 days.

BDSH will eventually evolve and be refined into the HelenOS equivalent

BDSH will eventually evolve and be refined into the HelenOS equivalent

of Busybox. While BDSH is now very intrinsic to HelenOS, its structure and

of Busybox. While BDSH is now very intrinsic to HelenOS, its structure and

use of strictly lower level functions makes it extremely easy to port.

use of strictly lower level functions makes it extremely easy to port.

Design:

Design:

=======

=======

BDSH is made up of three basic components:

BDSH is made up of three basic components:

 1. Main i/o, error handling and task management

 1. Main i/o, error handling and task management

 2. The builtin sub system

 2. The builtin sub system

 3. The module sub system

 3. The module sub system

The main part handles user input, reports errors, spawns external tasks and

The main part handles user input, reports errors, spawns external tasks and

provides a convenient entry point for built-in and modular commands. A simple

provides a convenient entry point for built-in and modular commands. A simple

structure, cliuser_t keeps track of the user's vitals, such as their current

structure, cliuser_t keeps track of the user's vitals, such as their current

working directory (and eventually uid, home directory, etc if they apply).

working directory (and eventually uid, home directory, etc if they apply).

This part defines and exposes all functions that are not intrinsic to a

This part defines and exposes all functions that are not intrinsic to a

certain built in or modular command. For instance: string handlers,

certain built in or modular command. For instance: string handlers,

module/builtin search and launch functions, error handlers and other things

module/builtin search and launch functions, error handlers and other things

can be found here.

can be found here.

Builtin commands are commands that must have access to cliuser_t, which is

Builtin commands are commands that must have access to cliuser_t, which is

not exposed to modular commands. For instance, the 'cd' command must update

not exposed to modular commands. For instance, the 'cd' command must update

the current working directory, which is stored in cliuser_t. As such, the

the current working directory, which is stored in cliuser_t. As such, the

entry types for builtin commands are slightly different.

entry types for builtin commands are slightly different.

Modular commands do not need anything more than the basic functions that are

Modular commands do not need anything more than the basic functions that are

exposed by default. They do not need to modify cliuser_t, they are just self

exposed by default. They do not need to modify cliuser_t, they are just self

contained. A modular command could very easily be made into a stand alone

contained. A modular command could very easily be made into a stand alone

program, likewise any stand alone program could easily become a modular

program, likewise any stand alone program could easily become a modular

command.

command.

Both modular and builtin commands share two things in common. Both must have

Both modular and builtin commands share two things in common. Both must have

two entry points, one to invoke the command and one to invoke a help display

two entry points, one to invoke the command and one to invoke a help display

for the command. Exec (main()) entry points are int * and are expected to

for the command. Exec (main()) entry points are int * and are expected to

return a value. Help entry points are void *, no return value is expected.

return a value. Help entry points are void *, no return value is expected.

They are typed as such (from cmds.h):

They are typed as such (from cmds.h):

/* Types for module command entry and help */

/* Types for module command entry and help */

/* Built-in commands need to be able to modify cliuser_t */

/* Built-in commands need to be able to modify cliuser_t */

As you can see, both modular and builtin commands expect an array of

As you can see, both modular and builtin commands expect an array of

arguments, however bulitins also expect to be pointed to cliuser_t.

arguments, however bulitins also expect to be pointed to cliuser_t.

Both are defined with the same simple structure:

Both are defined with the same simple structure:

/* Module structure */

/* Module structure */

typedef struct {

typedef struct {

	char *name;         /* Name of the command */

	char *name;         /* Name of the command */

	char *desc;         /* Description of the command */

	char *desc;         /* Description of the command */

	mod_entry_t entry;  /* Command (exec) entry function */

	mod_entry_t entry;  /* Command (exec) entry function */

	mod_help_t help;    /* Command (help) entry function */

	mod_help_t help;    /* Command (help) entry function */

	int restricted;     /* Restricts to interactive/non-interactive only */

	int restricted;     /* Restricts to interactive/non-interactive only */

} module_t;

} module_t;

NOTE: Builtin commands may grow in this respect, that is why they are

NOTE: Builtin commands may grow in this respect, that is why they are

defined separately.

defined separately.

Builtins, of course, would use the builtin_entry_t type. The name of the

Builtins, of course, would use the builtin_entry_t type. The name of the

command is used to associate user input to a possible entry point. The

command is used to associate user input to a possible entry point. The

description is a short (40 - 60 chars) summary of what the command does. Both

description is a short (40 - 60 chars) summary of what the command does. Both

entry points are then defined, and the restrict value is used to determine a

entry points are then defined, and the restrict value is used to determine a

commands availability.

commands availability.

Restriction levels are easy, a command is either available exclusively within

Restriction levels are easy, a command is either available exclusively within

interactive mode, exclusively within non-interactive mode or both. If you are

interactive mode, exclusively within non-interactive mode or both. If you are

looking at a prompt, you are in interactive mode. If you issue a command like

looking at a prompt, you are in interactive mode. If you issue a command like

this:

this:

/sbin/bdsh command [arg1] [arg2]

/sbin/bdsh command [arg1] [arg2]

... you are in non interactive mode. This is done when you need to force the

... you are in non interactive mode. This is done when you need to force the

parent shell to be the one who actually handles the command, or ensure that

parent shell to be the one who actually handles the command, or ensure that

/sbin/ls was used in lieu of the built in 'ls' when in non-interactive mode.

/sbin/ls was used in lieu of the built in 'ls' when in non-interactive mode.

The values are:

The values are:

  0 : Unrestricted

  0 : Unrestricted

 -1 : Interactive only

 -1 : Interactive only

  1 : Non-interactive only

  1 : Non-interactive only

A script to generate skeletal files for a new command is included, it can be

A script to generate skeletal files for a new command is included, it can be

found in cmds/mknewcmd. To generate a new modular command named 'foo', which

found in cmds/mknewcmd. To generate a new modular command named 'foo', which

should also be reachable by typing 'f00', you would issue this command:

should also be reachable by typing 'f00', you would issue this command:

./mknewcmd -n foo -a f00 -t module

./mknewcmd -n foo -a f00 -t module

This generates all needed files and instructs you on how to include your new

This generates all needed files and instructs you on how to include your new

command in the build and make it accessible. By default, the command will be

command in the build and make it accessible. By default, the command will be

unrestricted. Builtin commands can be created by changing 'module' to

unrestricted. Builtin commands can be created by changing 'module' to

'builtin'

'builtin'

There are more options to mknewcmd, which allow you to specify the

There are more options to mknewcmd, which allow you to specify the

description, entry point, help entry point, or restriction. By default, names

description, entry point, help entry point, or restriction. By default, names

just follow the command such as cmd_foo(), help_cmd_foo(), 'The foo command',

just follow the command such as cmd_foo(), help_cmd_foo(), 'The foo command',

etc. If you want to see the options and explanations in detail, use

etc. If you want to see the options and explanations in detail, use

./mknewcmd --help.

./mknewcmd --help.

When working with commands, keep in mind that only the main and help entry

When working with commands, keep in mind that only the main and help entry

points need to be exposed. If commands share the same functions, put them

points need to be exposed. If commands share the same functions, put them

where they are exposed to all commands, without the potential oops of those

where they are exposed to all commands, without the potential oops of those

functions going away if the command is eliminated in favor of a stand alone

functions going away if the command is eliminated in favor of a stand alone

external program.

external program.

The util.c file is a great place to put those types of functions.

The util.c file is a great place to put those types of functions.

Also, be careful with globals, option structures, etc. The compiler will

Also, be careful with globals, option structures, etc. The compiler will

generally tell you if you've made a mistake, however declaring:

generally tell you if you've made a mistake, however declaring:

volatile int foo

volatile int foo

... in a command will allow for anything else to pick it up. Sometimes

... in a command will allow for anything else to pick it up. Sometimes

this could be desirable .. other times not. When communicating between

this could be desirable .. other times not. When communicating between

builtins and the main system, try to use cliuser_t. The one exception

builtins and the main system, try to use cliuser_t. The one exception

for this is the cli_quit global, since everything may at some point

for this is the cli_quit global, since everything may at some point

need to check it. Modules should only communicate their return value.

need to check it. Modules should only communicate their return value.

Symbolic constants that everything needs should go in the config.h file,

Symbolic constants that everything needs should go in the config.h file,

however this is not the place to define shared macros.

however this is not the place to define shared macros.

Making a program into a module

Making a program into a module

==============================

==============================

If you have some neat program that would be useful as a modular command,

If you have some neat program that would be useful as a modular command,

converting it is not very hard. The following steps should get you through

converting it is not very hard. The following steps should get you through

the process easily (assuming your program is named 'foo'):

the process easily (assuming your program is named 'foo'):

1: Use mknewcmd to generate the skeletal files.

1: Use mknewcmd to generate the skeletal files.

2: Change your "usage()" command as shown:

2: Change your "usage()" command as shown:

     -- void usage(...)

     -- void usage(...)

     'level' is either 0 or 1, indicating the level of help requested.

     'level' is either 0 or 1, indicating the level of help requested.

     If the help / usage function currently exits based on how it is

     If the help / usage function currently exits based on how it is

     called, you'll need to change it.

     called, you'll need to change it.

3: Change the programs "main()" as shown:

3: Change the programs "main()" as shown:

     -- int main(int argc, char **argv)

     -- int main(int argc, char **argv)

     -- return 1;

     -- return 1;

     ++ return CMD_FAILURE;

     ++ return CMD_FAILURE;

     -- return 0;

     -- return 0;

     ++ return CMD_SUCCESS;

     ++ return CMD_SUCCESS;

     NOTE: If main is void, you'll need to change it and ensure that its

     NOTE: If main is void, you'll need to change it and ensure that its

     expecting an array of arguments, even if they'll never be read or

     expecting an array of arguments, even if they'll never be read or

     used. I.e.:

     used. I.e.:

     -- void main(void)

     -- void main(void)

4: Don't expose more than the entry and help points:

4: Don't expose more than the entry and help points:

     -- void my_function(int n)

     -- void my_function(int n)

     ++ static void my_function(int n)

     ++ static void my_function(int n)

5: Copy/paste to the stub generated by mknewcmd then add your files to the

5: Copy/paste to the stub generated by mknewcmd then add your files to the

   Makefile. Be sure to add any directories that you made to the SUBDIRS so

   Makefile. Be sure to add any directories that you made to the SUBDIRS so

   that a 'make clean' will clean them.

   that a 'make clean' will clean them.

Provided that all functions that your calling are available in the

Provided that all functions that your calling are available in the

userspace C library, your program should compile just fine and appear

userspace C library, your program should compile just fine and appear

as a modular command.

as a modular command.

Overcoming userspace libc obstacles

Overcoming userspace libc obstacles

===================================

===================================

A quick glance through the util.c file will reveal functions like

A quick glance through the util.c file will reveal functions like

cli_strdup(), cli_strtok(), cli_strtok_r() and more. Those are functions

cli_strdup(), cli_strtok(), cli_strtok_r() and more. Those are functions

that were missing from userspace libc when BDSH was born. Later, after

that were missing from userspace libc when BDSH was born. Later, after

porting what was needed from FBSD/NBSD, the real functions appeared in

porting what was needed from FBSD/NBSD, the real functions appeared in

the userspace libc after being tested in their cli_* implementations.

the userspace libc after being tested in their cli_* implementations.

Those functions remain because they guarantee that bdsh will work even

Those functions remain because they guarantee that bdsh will work even

on systems that lack them. Additionally, more BDSH specific stuff can

on systems that lack them. Additionally, more BDSH specific stuff can

go into them, such as error handling and reporting when malloc() fails.

go into them, such as error handling and reporting when malloc() fails.

You will also notice that FILE, fopen() (and all friends), ato*() and

You will also notice that FILE, fopen() (and all friends), ato*() and

other common things might be missing. The HelenOS userspace C library is

other common things might be missing. The HelenOS userspace C library is

still very young, you are sure to run into something that you want/need

still very young, you are sure to run into something that you want/need

which is missing.

which is missing.

When that happens, you have three options:

When that happens, you have three options:

1 - Implement it internally in util.c , when its tested and stable send a

1 - Implement it internally in util.c , when its tested and stable send a

patch to HelenOS asking for your function to be included in libc. This is

patch to HelenOS asking for your function to be included in libc. This is

the best option, as you not only improve BDSH .. but HelenOS as a whole.

the best option, as you not only improve BDSH .. but HelenOS as a whole.

2 - Work around it. Not everyone can implement / port fopen() and all of

2 - Work around it. Not everyone can implement / port fopen() and all of

its friends. Make open(), read(), write() (etc) work if at all possible.

its friends. Make open(), read(), write() (etc) work if at all possible.

3 - Send an e-mail to the HelenOS development mailing list. Explain why you

3 - Send an e-mail to the HelenOS development mailing list. Explain why you

need the function and what its absence is holding up.

need the function and what its absence is holding up.

If what you need is part of a library that is typically a shared object, try

If what you need is part of a library that is typically a shared object, try

to implement a 'mini' version of it. Currently, all userspace applications

to implement a 'mini' version of it. Currently, all userspace applications

are statically linked. Giving up creature comforts for size while avoiding

are statically linked. Giving up creature comforts for size while avoiding

temporary 'band aids' is never frowned upon.

temporary 'band aids' is never frowned upon.

Most of all, don't get discouraged .. ask for some help prior to giving up

Most of all, don't get discouraged .. ask for some help prior to giving up

if you just can't accomplish something with the limited means provided.

if you just can't accomplish something with the limited means provided.

Contributing

Contributing

============

============

I will take any well written patch that sanely improves or expands BDSH. Send

I will take any well written patch that sanely improves or expands BDSH. Send

me a patch against the trunk revision, or, if you like a Mercurial repository

me a patch against the trunk revision, or, if you like a Mercurial repository

is also maintained at http://echoreply.us/hg/bdsh.hg and kept in sync with

is also maintained at http://echoreply.us/hg/bdsh.hg and kept in sync with

the trunk.

the trunk.

Please be sure to follow the simple coding standards outlined at

Please be sure to follow the simple coding standards outlined at

http://www.helenos.eu/cstyle (mostly just regarding formatting), test your

http://www.helenos.eu/cstyle (mostly just regarding formatting), test your

changes and make sure your patch applies cleanly against the latest revision.

changes and make sure your patch applies cleanly against the latest revision.

All patches submitted must be your original code, or a derivative work of

All patches submitted must be your original code, or a derivative work of

something licensed under the same 3 clause BSD license as BDSH. See LICENSE

something licensed under the same 3 clause BSD license as BDSH. See LICENSE

for more information.

for more information.

When sending patches, you agree that your work will be published under the

When sending patches, you agree that your work will be published under the

same 3 clause BSD license as BDSH itself. Failure to ensure that anything

same 3 clause BSD license as BDSH itself. Failure to ensure that anything

you used is not under the same or less restrictive license could cause major

you used is not under the same or less restrictive license could cause major

issues for BDSH in the future .. please be sure. Also, please don't forget

issues for BDSH in the future .. please be sure. Also, please don't forget

to add yourself in the AUTHORS file, as I am horrible about keeping such

to add yourself in the AUTHORS file, as I am horrible about keeping such

things up to date.

things up to date.