www.nico.schottelius.org/software/cinit/browse_source/cinit-0.3pre13/doc/devel/communication.text

cinit - communication
=====================
Nico Schottelius <nico-linux-cinit__@__schottelius.org>
0.1 for cinit-0.3, Initial version: 2006-08-11
:Author Initials: NS

This document describes the internal communication of cinit.
It is thought to be read by developers.


Introduction
------------
This document describes the messages used between cinit, cinit forks
and other programs that want to talk to cinit. It does NOT
describe the communication method, but only the messages sent
(for the communication method read "ipc.text").

Document status
~~~~~~~~~~~~~~~
This document is still being written, it is not finished.


About Messages
--------------

Order
~~~~~
The client always initiates the communication.
cinit will begin listening to messages directly after its start.


Numbers
~~~~~~~
Can be found in include/cinit.h.


Data
~~~~~
A message always conists of a predefined structure (see src/headers/comm.h).
Can't use a structure, were missing the point that we cannot transfer dynamic
length strings. Thus the protocol consists of:

   client(int) => cinit
   cinit(ini) => client
   => after that follows command specific data

The byte order is host specific (may be little or big endian).

STRUCTURE WITH STATIC SIZE. MSGRCV!
IPC LAYER CREATES TRANSPORT!

Type
~~~~
Messages are binary data.

The messages
------------
The client always uses the same structure (struct msg_client) to contact
cinit. This way cinit does not need to handle dynamic data structures.

cinit in contrast delivers different data structures to its clients,
depending on the question.

The questions are issued by any type of client, the internal command used is
noted in square brackets ([]).

The answers are given by cinit.


Question: Start a service (and its dependencies) [CMD_START_SVC]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is issued either by a cinit fork or by an external client.
cinit will start a fork, which tries to start the service and its dependencies.

The client must provide cinit with the following information:
. Name of the service to be started
. Reason why to start it
. eventually additional information (see below)

The reason
^^^^^^^^^^
Can be one of:
- RS_NONE   (it's a manual start request)
- RS_WANTS  (a currently starting service wants to start this service)
- RS_NEEDS  (a currently starting service needs to start this service)

If the reason is RS_WANTS or RS_NEEDS the client must supply the name
of the service, which wants it to be started.


Question: Start a service (nothing else) [CMD_START_SVC_ONLY]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will start a fork, which tries to start the service and which will
report the status back.


Question: Stop a service (and its dependencies) [CMD_STOP_SVC]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is issued either by a cinit fork or by an external client.
cinit will start a fork, which tries to stop the service and each service
that 'needs' it.

This function works recursively, thus also killing those services, that
need the service that need the current service.


Question: Stop a service (nothing else) [CMD_STOP_SVC_ONLY]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will start a fork, which tries to stop this service and which will
report the status back.


Question: Stop a service (plus 'needs' and 'wants') [CMD_STOP_SVC_WANTS]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Same as 'Stop a service (and its dependencies)', but also stop the
services that want to have this service.

This function works recursively, thus also killing those services, that
'need' or 'want' the service that 'need' or 'want' the current service.


Question: What's the status of service XYZ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Code, length of service name, the service name (without \0).
int, int, char[];



Question: Could you change the status? [CMD_CHG_STAT]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A cinit fork reports the new status of a service.


Question: Could you start the rescue mode? [CMD_RESCUE]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will not give an answer to this question.
cinit will stop all services, kill all other processes and after that
spawn the rescue program.


Question: Could you halt the system? [CMD_HALT]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will not give an answer to this question.
cinit will stop all services, kill all other processes and after that
halt the system.


Question: Could you reboot the system? [CMD_REBOOT]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will not give an answer to this question.
cinit will stop all services, kill all other processes and after that
reboot the system.


Question: Could you poweroff the system? [CMD_POWEROFF]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will not give an answer to this question.
cinit will stop all services, kill all other processes and after that
poweroff the system. If poweroff is not possible, the system will
be halted.


Question: Could you warmboot the system? [CMD_WBOOT]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will not give an answer to this question.
cinit will stop all services, kill all other processes and after that
restart itself and the bootup process.


Question: Could you send information about a service? [CMD_INFO]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command may only be issued by an external client.
cinit will respond with detailled information about the service
to the client.


Answer: Return short status of a service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This answer is used as a response to:

   - Question: Start a service (and its dependencies)
   - Question: Start a service (nothing else)
   - Question: Stop a service (and its dependencies)
   - Question: Stop a service (nothing else)
   - Question: Stop a service (plus 'needs' and 'wants')
   - Question: Could you change the status?

cinit only responds the status of the asked service.
The structure send is "asw_sstatus", which only include a status byte.


Answer: Return long status of a service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This answer is used as a response to:

   - Question: Could you send information about a service?


old Messages (to be transferred into this document)
---------------------------------------------------
   CMD_START_SVC:    I want to start a service.
   CMD_CHG_STATUS:   I want to change the status of a service.
   CMD_STOP_SVC:     Please shutdown a service.

   CMD_RESCUE:       Kill everything, and spawn a sulogin shell.
   CMD_UPDATE:       Hot-reboot system and reload cinit.

   CMD_HALT:         Halt the system
   CMD_REBOOT:       Reboot the system
   CMD_POWEROFF:     Power-off the system

--------------------------------------------------------------------------------
Service status:

--------------------------------------------------------------------------------
service status (cinit),
Nico Schottelius 2005-09-29 (Last Modified: -)
--------------------------------------------------------------------------------

There are service status and service returns. Service status is a status
a service can have. A service return is a value from a function that
describes what happened with the service.

Status has ST_ prefix, return has RT_ prefix.
See cinit.h for most up to date versions.


ST_NEED_FAIL      - this service will not be started, until the needs are started
ST_FAIL           - this service failed to start
ST_UNSPEC         - some unknown error. This should never happen.
ST_ERR            - ???  /* tried earlier, service failed, won't retry */

ST_SUCCESS        - service was successfully started - senseful?
ST_TMP            - some instance is currently working on it
ST_ONCE           - executed once  sucessfully
ST_RESPAWN        - service is running and respawning

ST_TMPNOW    55        /* now you are on it - only for clients */
#define ST_OFF       56        /* Switching service off */