248 lines
8.3 KiB
Text
248 lines
8.3 KiB
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 */
|
|
|