MULTICS TECHNICAL BULLETIN MTB-663, Revision 3
To: MTB Distribution
From: Rich Fawcett
Paul Farley
Date: March 12, 1986
Subject: Management of the on-line communication between the
Maintenance Channel Adapter (MCA), located within the Integrated
Multiplexer Unit (IMU), and Multics.
This MTB describes the plans for attaching and controlling
communication between a Multics process and an MCA for performing
various functions. These will include reading the current IMU
configuration state, reading selected information from one of the
two internal IMU diskette devices and performing Integrated
Peripheral Controller (IPC) functions (once the IPC has also been
attached).
All attachments will be performed by calls through the mca_ gate
in ring_1, which will then call rcp_ to perform the actual
attachment. No attachment or I/O to MCAs or IPCs will be allowed
outside of ring_1. This will force all calls to ioi_ for the I/O
operations to be executed from the ring_1 mca programs.
This interface will allow simple and secure access to information
contained in the IMU.
This is the third revision of MTB663. This revision defines the |
security auditing trail, and now reflects the current |
implementation of the interface. It carries change bars as |
related to revision 02. |
Comments on this MTB should be placed in the DIPPER_Development
forum on System M:
>udd>m>CLJones>mtgs>DIPPER_Development (nio)
or directed by Multics mail to:
System M: Fawcett.Multics and / or Farley.Multics
or by phone to:
Rich Fawcett or Paul Farley
HVN: 249-6777 HVN: 249-6776
DDD: 602-249-6777 DDD: 602-249-6776
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced or distributed outside the Multics Project.
MTB-663, Revision 3 MCA Online-Management
CONTENTS
Page
1: Introduction . . . . . . . . . . . . . . . . . 1
2: MCA Attachment Detachment . . . . . . . . . . . 3
3: Privileged MCA Operations . . . . . . . . . . . 5
4: Miscellaneous MCA Operations . . . . . . . . . 6
5: IPC Adapter Attachment Detachment . . . . . . . 7
6: Standard IPC Operations . . . . . . . . . . . . 8
7: On-Line T&D Requirements . . . . . . . . . . . 9
| 8: Auditing Trail and Functional Tests . . . . . . 10
9: MCA Subroutine Descriptions . . . . . . . . . . 10
mca_ . . . . . . . . . . . . . . . . . . . . . . . 11
mca_$attach_ipc . . . . . . . . . . . . . . . 11
mca_$attach_mca . . . . . . . . . . . . . . . 12
mca_$config . . . . . . . . . . . . . . . . . 13
mca_$detach_ipc . . . . . . . . . . . . . . . 15
mca_$detach_mca . . . . . . . . . . . . . . . 16
mca_$diskette_read . . . . . . . . . . . . . . 17
mca_$display . . . . . . . . . . . . . . . . . 19
mca_$load_ipc . . . . . . . . . . . . . . . . 20
mca_$process_io_event . . . . . . . . . . . . 21
mca_$read_data . . . . . . . . . . . . . . . . 22
mca_$reset_ipc . . . . . . . . . . . . . . . . 24
mca_$reset . . . . . . . . . . . . . . . . . . 25
mca_$tandd_read_data . . . . . . . . . . . . . 26
mca_$tandd_write_data . . . . . . . . . . . . 28
mca_$tandd_write_text . . . . . . . . . . . . 29
mca_priv_ . . . . . . . . . . . . . . . . . . . . . 31
mca_priv_$load_ipcs . . . . . . . . . . . . . 31
mca_priv_$reset_ipcs . . . . . . . . . . . . . 32
mca_priv_$force_reset . . . . . . . . . . . . 33
mca_priv_$force_unlock . . . . . . . . . . . . 34
mca_priv_$trace . . . . . . . . . . . . . . . 35
Appendix A: mca_workspace . . . . . . . . . . . . 36
Appendix B: mca_config_file . . . . . . . . . . . 41
Appendix C: mca_area . . . . . . . . . . . . . . . 45
Appendix D: mca_data_seg . . . . . . . . . . . . . 46
Appendix E: mca_diskette . . . . . . . . . . . . . 49
Appendix F: mca_return_status . . . . . . . . . . 51
MCA Online-Management MTB-663, Revision 3
1: INTRODUCTION
With the introduction of the IMU, which will replace the
current functions of the IOM, comes the existence of an
internal maintenance processor, MCA, that oversees all of
the overhead functions of the IMU. These include
initialization of the IMU and IPCs, firmware loading of the
IPC adapters using one of the two internal diskette devices,
bootload tape reading, interrogation of IMU to IPC hardware
and firmware data using overlays from the diskettes,
executing tests on the IPC adapters, internal configuration
file maintenance, plus all fault handling, IMU and IPC.
The MCA has two possible communication paths.
1) Through a special interface called the Multidrop
Interface (MDI) which allows one or more MCAs to be
connected to a IPC adapter called the IPC-CONS-2. This
could be the adapter used to connect the BOS or BCE
console or a separate console only for MCA I/O. This
is the path used to initially initialize, load firmware
and boot the IMU. Communication is done by special
input sequences at the console which allows the
operator to select and send input to the right MCA.
This interface, along with the remote console
interface, should be LOCKED while the system is
running, this is done by issuing special command
sequences to the master console adapter. The MCA will
still be able to output messages to the console, but NO
input to the MCA would be allowed by the console. This
will force the use of the mca_ gate while the system is
up.
2) Through overhead channel #03 in the IMU, which is the
path used by Multics and which this MTB is all about.
Because of the possible security violations (and other
disastrous things) that could occur by allowing uncontrolled
communication through channel 3, it is necessary that all
I/O to the MCA be either created by a secure ring_1 program
or passed though a ring_1 interface that can verify that the
MCA command text is only going to affect the IPC that has
been previously attached.
It should still be noted that this gate can perform highly
privileged operations, like read any information off a
currently mounted diskette and possibly write data to a
diskette if the MCA allows the operation in the future.
Access to the mca_ and mca_priv_ gates should be closely
monitored.
MTB-663, Revision 3 MCA Online-Management
Having an internal Multics program perform the I/O also
allows the calling program to not have to be concerned with
the format of the I/O to and from the MCA, only the
information desired.
| This MTB is divided into nine sections that will cover the
| following:
o steps required to attach or detach an MCA (section 2).
o privileged MCA operations (section 3).
o miscellaneous MCA operations (section 4).
o steps required to attach or detach an IPC (section 5).
o standard IPC operations (section 6).
| o on-line t&d requirements (section 7).
| o auditing trail and functional tests (section 8)
| o subroutine descriptions (section 9).
There are six appendices that show the data structures and
return status. These appendices are not the PL/I include
files used, but are similar and appear as part of this MTB
for documentation reference only.
MCA Online-Management MTB-663, Revision 3
2: MCA ATTACHMENT DETACHMENT
Prior to performing any I/O between the MCA and Multics the
user must attach a specific MCA to their process.
It will be required that there be an ACS segment for each
configured IMU on the system. The ACS segment will have the
form "mcaX.acs", where X will equal "a" through "d" and
correspond to the configurations "IOM" card definition. The
ring brackets on the ACS segment will be set to 1, 1, 1 to
force attachments to only be made by ring 0 or 1 (ie.
through the mca_ gate).
During system startup the following steps will be performed.
1. ioi_init will scan the configuration file and for all
IOM cards that contain a iom-type of IMU it will create
entries in ioi_data for the MCA that will allow
communication through ioi_ during system operation.
2. rcp_init will scan the configuration file and for all
IOM cards that contain an iom-type of IMU it will
create entries in rcp_data defining the configured MCAs
as a new type of device called "mca" with names of
"mcaa", "mcab", "mcac" or "mcad". The module mca_init
will be called at this time for each of the mca
entries. It sets up a skeleton segment in
>system_library_1, called mca_data_seg, that will be
used by the mca modules to control their activities
during system operation.
3. rcp_ring1_init_ will create ACS segments for the mca
type entries in rcp_data and set the ring brackets to
1,1,1.
The user process will call the mca_$attach_mca entry, which
will make all the necessary calls to RCP, from ring 1, and
upon good attachment return a IOI index that will be used
for all subsequent calls to other mca_ entries. If the MCA
is currently attached to another process or the user has
insufficient access to attach the MCA a standard system
error code will be returned. If the user specifies an
event_channel in the call, to be used for asynchronous
process execution, it will be necessary for the user to call
mca_$process_io_event each time an event is signalled over
the event channel until the requested task has been
completed. This also includes the attachment I/O. If no
event channel is specified then one will be made in ring 1
and all I/O will be blocked (i.e. synchronous).
During the attachment three I/Os will be performed. The
first will reset the MCA to a known state. The second will
MTB-663, Revision 3 MCA Online-Management
extract the current IMU configuration data from the MCA's
internal memory, which will be placed in mca_data, to be
used for all other activity. The third will terminate the
MCA session.
Only one user will be allowed to attach a given MCA at one
time, but there can be attachments to other MCAs by the same
or other processes.
After a maintenance session is finished it will be the users
responsibility to detach the MCA. This will be done by
calling the mca_$detach_mca entry, specifying the ioi_index
of the attachment. This will detach any IPCs that have been
attached, if they have not been previously detached.
For fatal process errors, disconnections and system crashes
RCP will call the mca modules to detach any attached IPCs,
clean up the mca_data segment and force detach the MCA.
MCA Online-Management MTB-663, Revision 3
3: PRIVILEGED MCA OPERATIONS
The MCA allows several off-line (through the console)
commands that cause events to happen to ALL of the IPC
adapters in the unit. These are to either RESET all the IPC
adapters (i.e. cause them to initialize and run self-tests
if required), or to LOAD all the IPC adapters (i.e. same as
RESET, but the internal adapter firmware would also be
reloaded).
In an on-line environment it would not be advantageous to
allow these types of commands to be sent to the MCA, without
first verifying that all system I/O to and from the IPCs is
stopped. The easiest way to know this is to require the
user to attach all the IPCs on the IMU.
There will be three types of commands allowed through the
privileged gate. One will be to allow MCA tracing (i.e.
displaying of MCA fault and debug messages) to be turned on
or off. IPC attachment is not required. The second will be
to reset all the configured IPC adapters on the IMU to a
known state. The third will be to load firmware into all
the configured IPC adapters that are loadable. The others
will only be reset (e.g. the ipc-psia requires no
firmware). The attachment of all the IPCs is required for
the second and third types.
MTB-663, Revision 3 MCA Online-Management
4: MISCELLANEOUS MCA OPERATIONS
There are currently two miscellaneous MCA operations that
can be done. One is to have the MCA return the current
configuration of the IMU. This configuration contains
various information about the type, location, state,
channels and firmware identification for all the IPCs in the
IMU, plus IMU specific information like what memory ports
are available and how they are configured.
The second is the ability to read various data from one of
the two diskette devices connected to the MCA. It will be
possible to read the diskette header (label), directory and
files.
It should be noted that after either of these operations are
done, the mca_$read_data entry must be called to terminate
the MCA session. This is due to a design flaw in the MCA
firmware. The session is NOT over until the MCA can return
NO data back to the user. A status of "00/02", major and
sub, indicates session complete.
MCA Online-Management MTB-663, Revision 3
5: IPC ADAPTER ATTACHMENT DETACHMENT
Prior to executing any I/O to the MCA that will be directed
to a specific IPC adapter, all the normal I/O channels to
the adapter must be attached to the user process and all I/O
through these channels suspended.
The user process will call the mca_$attach_ipc entry,
specifying an ipc_id which can be an IPC (e.g. "ipc06") or
a IOM and Channel (e.g. "B34") to attach. The entry will
validate the specified IPC, or channel by examining the
mca_data segment kept in >system_library_1. If the user
selected an IPC that is not configured, the IPC is marked as
attached and a good code is returned. Otherwise RCP is
called to attach the IPC and IOI is called to suspend the
I/O through the IPC (if disk or tape). If any of this is
unable to be performed then anything attached in this call
will be detached and a standard system error code will be
returned. Otherwise a zero code will be returned indicating
successful attachment.
After a maintenance session is finished it will be the users
responsibility to detach the IPC. This will be done by
calling the mca_$detach_ipc entry, specifying the ipc_id and
mca_ioi_idx used during the attachment.
For fatal process errors, disconnections and system crashes
RCP will force detach the IPC and MCA.
MTB-663, Revision 3 MCA Online-Management
6: STANDARD IPC OPERATIONS
Once an IPC adapter is successfully attached the user
process can execute the mca_ entries that will either
execute the MCA "LOAD IPC N" (mca_$load_ipc) or the MCA
"RESET IPC N" (mca_$reset_ipc) commands.
All of the IPC test functions will be performed by the TOLTS
environment, which will use the mca_ entries described in
section 7.
MCA Online-Management MTB-663, Revision 3
7: ON-LINE T&D REQUIREMENTS
The On-line Test and Diagnostics programs that will be run
on the IPC adapters will be executed from the TOLTS program.
A GCOS Maintenance Channel Adapter Driver (MCAD) program
will be the actual origin of the tests, which will be run
under the MOLTS executive.
This driver was written to allow GCOS to communicate with
the MCA, directly. So all of the necessary I/O block
structuring (IDCWs, DCWs and data areas) are being built by
the driver.
For this program to run on Multics it will be necessary to
have three separate gate entries in the mca_ interface that
will allow this program to pass its I/O blocks through. One
will be used for early communication with the MCA and
passing of data during actual IPC functions
(mca_$tandd_write_data). Another will be used to initiate
operations that will affect the attached IPC
(mca_$tandd_write_text). The third will be a read only
entry used when the returned data is larger that the area
reserved (mca_$tandd_read_data).
The early communication will be for the MCA to aid the user
in selecting the proper test requests, no actual operations
will be allowed by the MCA until the MCA receives a "initial
test request" IDCW (only sendable from the tandd_write_text
entry). Once this early communication is done the MCAD
routine will have the proper text to send to the MCA to
initiate the selected function. The only MCA/IPC requests
that will be allowed are read config, reset (ipc), load
(ipc), rload (ipc) and test (ipc) all others will be
rejected with a system error code.
The MCAD program will ask for the IPC to be attached, which
will cause the TOLTS program to call the mca_$attach_ipc
entry. When the IPC has been attached, MCAD will ask that
the MCA I/O block be sent to the MCA as a initial test
request. TOLTS will pass this along to the
mca_$tandd_write_text entry where the text will be verified
as only affecting the attached IPC and passed to the MCA.
The mca_ entries will wire down an area for the TOLTS I/O
block to be moved and also replace the IDCW/DCWs with known
valid ones. The mca_ routines in ring 1 will then
communicate with ioi_ to perform the actual I/O. When the
I/O is complete the portion of the wired I/O block with data
from the MCA will be returned to the TOLTS area and status
returned to TOLTS.
MTB-663, Revision 3 MCA Online-Management
| 8: AUDITING TRAIL AND FUNCTIONAL TESTS
| Security auditing is done for errors found that may effect
| the security of the system when the mca_$tandd_write_text
| entry is used. These conditions are:
| o A request other than any listed in section 7 is issued.
| o The request is for an unattached IPC.
| o The request is for an object other than an IPC.
| Due to the overhead of auditing, only the DENIED requests
| are audited. It is the responsibility of the RCP/RCPM
| subsystem to audit the attachment and detachment of the
| selected MCA.
| The messages are standard auditing messages, and are placed
| into the syserr_log by calls to
| access_audit_r1_$log_general. This uses the added operation
| of access_operations_$invalid_mca. The selection criteria
| is:
| o system object of OTHER
| o operation status of DENIED
| o operation type of READ
| o operation code of "invalid mca command"
| o operation mode of PRIVILEGED OPERATION
| The audit message contain the error returned to the user as
| well as the complete request line.
| Functional testing consists of DAC and MAC testing for the
| ACS and data segments, and AUDIT testing for the
| mca_$tandd_write_text gate entry. There is no need for
| LABEL and IA testing.
9: MCA SUBROUTINE DESCRIPTIONS
The following pages will describe the various mca_ and
mca_priv_ entry points that will be available for use.
____ ____
mca_ mca_
____ ____
Name: mca_
Entry: mca_$attach_ipc
This entry will be used to attach a selected IPC to a user
process. The user must have previously attached the MCA,
that will communicate with the IPC.
Usage
dcl mca_$attach_ipc entry (char (*), fixed bin, fixed bin,
fixed bin (35));
call mca_$attach_ipc (ipc_id, mca_ioi_idx, ipc_num, code);
where:
ipc_id
IPC name to be attached. The name must be either the form
"ipcN", where N would be the IPC number 0 through 15, or
"ICC", where "I" would be the tag of the MCA (i.e. A, B, C or
D) and CC would be a channel number that is assigned to the
IPC. (Input)
mca_ioi_idx
IOI index value that was returned when MCA was attached.
(Input)
ipc_num
The real IPC number (0 - 15) that was attached. This is the
number to be used with the load and reset entries. (Output)
code
Will be zero if attachment was successful, else a standard
system status code will be returned. (Output)
Notes
When an IPC is attached, it is sometimes necessary to suspend all
system I/O through all the logical channels. If required, this
entry will attempt to perform this task. If it is not possible
to suspend the I/O, the IPC will NOT be attached and an error
code returned.
____ ____
mca_ mca_
____ ____
Entry: mca_$attach_mca
This entry will be used to attach a selected MCA to a user
process.
Usage
dcl mca_$attach_mca entry (char (*), fixed bin (71), fixed bin,
fixed bin (35));
call mca_$attach_mca (mca_id, mca_ev_chn, mca_ioi_idx,
code);
where:
mca_id
MCA name to be attached. The name must be in the form "mcaX",
where X will be equal to the letter of the IMU the MCA is in
(a, b, c, or d). (Input)
mca_ev_chn
Event channel that will be used to signal completion of MCA
I/O. If it is a value other than 0 or 1,
then completion of the I/O for this MCA will be handled using
the event method and it will be required for the user to call
mca_$process_io_event for each I/O completion, until the task
is complete including the attachment task. Otherwise all
entries that perform I/O will use ipc_$block to wait for the
I/O to complete before returning from the call. The process
will go blocked in ring_1 for this case. (Input)
mca_ioi_idx
IOI index value that will be returned when the MCA is
successfully attached. (Output)
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Entry: mca_$config
This entry will return the contents of the IMU configuration data
currently residing in the MCA's RAM. The user will need to
provide sufficient space, defined by ret_ptr, to hold the the
information. The configuration data will be defined in a system
include file.
Usage
dcl mca_$config entry (fixed bin, ptr, fixed bin (21),
fixed bin (21) bit (36), fixed bin (35));
call mca_$config (mca_ioi_idx, ret_ptr, ret_size, ret_len
mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
ret_ptr
User area to return configuration data. (See Appendix B)
(Input)
ret_size
Maximum size of user area in characters. (Input)
ret_len
Actual number characters placed in the users area. (Output)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Notes
The entry mca_$read_data must also be called after receiving the
requested data to terminate the "session". Refer to section 4
(Miscellaneous MCA Operations) for details.
____ ____
mca_ mca_
____ ____
Entry: mca_$detach_ipc
This entry will be used to detach a IPC that is currently
attached to a user process.
Usage
dcl mca_$detach_ipc entry (char (*), fixed bin, bit (1),
fixed bin (35));
call mca_$detach_ipc (ipc_id, mca_ioi_idx, ipc_operational,
code);
where:
ipc_id
IPC name to be detached. The name must be either the form
"ipcN", where N would be the IPC number 0 through 15, or
"ICC", where "I" would be the tag of the MCA (i.e. A, B, C or
D) and CC would be a channel number that is part of the IPC.
(Input)
mca_ioi_idx
IOI index value that was returned when MCA was attached.
(Input)
ipc_operational
This bit controls the release of I/O that has been suspended
through the IPC. If the bit is true, then then IPC is
considered operational and the I/O will be released (if it had
been suspended). Otherwise the I/O will remain suspended and
the operator will be notified that the I/O was not released.
(Input)
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Entry: mca_$detach_mca
This entry will be used to detach the currently attached MCA from
a user process.
Usage
dcl mca_$detach_mca entry (fixed bin, fixed bin (35));
call mca_$detach_mca (mca_ioi_idx, code);
where:
mca_ioi_idx
IOI index value that was returned when MCA was attached.
(Input)
code
Will be a standard system status code. (Output)
Notes
If any IPCs on the MCA are attached they will be detached before
the MCA is detached.
____ ____
mca_ mca_
____ ____
Entry: mca_$diskette_read
This entry will allow selected information from one of the two
diskette devices to be returned to the caller.
Usage
dcl mca_$diskette_read entry (fixed bin, char (*), fixed bin,
ptr, fixed bin (21), fixed bin (21), bit (36),
fixed bin (35));
call mca_$diskette_read (mca_ioi_idx, read_type, disk_num,
ret_ptr, ret_size, ret_len, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
read_type
Defines what information is to be returned. The input will be
passed to the MCA without alteration. (See Appendix E)
(Input)
Valid inputs are:
"DIRECTORY" This will return the directory contents from
the selected diskette.
"HDR" This will return the contents of the
diskette header.
P=file_name This will return the contents of the
requested file_name.
VID/file_name The MCA will return file_name data, only if
a diskette labeled VID is mounted in either
of the 2 diskette devices. The disk_num
argument will not be used.
disk_num
This will define which diskette device to read the selected
data from. Valid values are 0 and 1. (Input)
ret_ptr
User area to return data. (Input)
____ ____
mca_ mca_
____ ____
ret_size
Maximum size of user area in characters. (Input)
ret_len
Actual number characters placed in the users area. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning the number of
characters placed in the user area).
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O.
code
Will be a standard system status code. (Output)
Notes
The entry mca_$read_data must also be called after receiving the
requested data to terminate the "session". Refer to section 4
(Miscellaneous MCA Operations) for details.
____ ____
mca_ mca_
____ ____
Entry: mca_$display
This entry will allow a user to extract the contents of the
ring-1 control segment, mca_data_seg, for examination. (See
Appendix D)
Usage
dcl mca_$display entry (ptr, fixed bin (21), fixed bin (21),
fixed bin (35));
call mca_$display (ret_ptr, ret_size, ret_len, code);
where:
ret_ptr
User area to return data. (Input)
ret_size
Maximum size of user area in characters. If this is less than
the size of the mca data, then only ret_size characters will
be returned. (Input)
ret_len
Actual number characters placed in the users area. (Output)
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Entry: mca_$load_ipc
This entry will allow the requested IPC to have its internal
firmware reloaded from the MCA diskette and reset to a
initialized state.
Usage
dcl mca_$load_ipc (fixed bin, fixed bin, bit (36),
fixed bin (35));
call mca_$load_ipc (mca_ioi_idx, ipc_number, mca_status,
code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
ipc_number
The IPC number to be acted on (returned by mca_$attach_ipc).
(Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the MCA is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
Notes
It will be necessary to attach an IPC, using the mca_$attach_ipc,
before invoking this entry. Otherwise an error code will be
returned.
____ ____
mca_ mca_
____ ____
Entry: mca_$process_io_event
Used to notify ring 1 of the completion of an asynchronous I/O
event. It may be necessary to call this entry several times
before a task is complete. This entry must only be used when a
event channel was passed to mca_$attach_mca entry point when the
MCA was attached.
Usage
dcl mca_$process_io_event entry (fixed bin, ptr, ptr,
fixed bin (35));
call mca_$attach_mca (mca_ioi_idx, event_call_info_ptr,
mca_area_ptr, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
event_call_info_ptr
Pointer to the event_call_info structure returned when the
event was signalled. (Input)
mca_area_ptr
Pointer to the user supplied area for placing I/O completion
information. (See Appendix C ). (Input)
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Entry: mca_$read_data
This entry must be used in cases, such as diskette read, where
the data to be sent by the MCA is larger that the size of the
user buffer. This is indicated by the status returned for that
call. This entry reads the remaining data from the MCA and
places it in the user buffer for this call. The status returned
must be checked to see if there is more data to read. Repeated
calls to this entry must be used to read the data.
Usage
dcl mca_$read_data entry (fixed bin, ptr, fixed bin (21),
fixed bin (21), bit (36), fixed bin (35));
call mca_$read_data (mca_ioi_idx, ret_ptr, ret_size,
ret_len, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
ret_ptr
User area to return data. (Input)
ret_size
Maximum size of user area in characters. (Input)
ret_len
Actual number characters placed in the users area. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning the number of
characters placed in the user area).
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O.
____ ____
mca_ mca_
____ ____
code
Will be a standard system status code. (Output)
Notes
This entry must also be used to terminate a "session", when
entries like config and diskette_read have been used. Refer to
section 4 (Miscellaneous MCA Operations) for details.
____ ____
mca_ mca_
____ ____
Entry: mca_$reset_ipc
This entry will allow the requested IPC to be reset to an
initialized state.
Usage
dcl mca_$reset_ipc (fixed bin, fixed bin, bit (36),
fixed bin (35));
call mca_$reset_ipc (mca_ioi_idx, ipc_number, mca_status,
code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
ipc_number
The IPC number to be acted on (returned by mca_$attach_ipc).
(Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the MCA is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
Notes
It will be necessary to attach an IPC, using the mca_$attach_ipc,
before invoking this entry. Otherwise an error code will be
returned.
____ ____
mca_ mca_
____ ____
Entry: mca_$reset
This entry will allow the user to reset the MCA to Multics
communication dialogue. This entry issues a reset_status opcode
("40"b3) to the MCA.
Usage
dcl mca_$reset (fixed bin, bit (36), fixed bin (35));
call mca_$reset (mca_ioi_idx, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the MCA is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Entry: mca_$tandd_read_data
This entry will allow the tolts subsystem to send previously
prepared IO blocks to the MCA. This entry must be used by tolts
to perform a read only operation from the MCA. This is the case
when the previous command status return indicates that the MCA
has more data to send than the tolts subsystem had reserved space
for. The IDCW and DCW will be supplied by the gated code. When
the MCA returns response data, it will be copied from the wired
block into the user area and the MCA status returned to the
caller.
Usage
dcl mca_$tandd_read_data (fixed bin, ptr, fixed bin, bit (36),
fixed bin (35));
call mca_$tandd_read_data (mca_ioi_idx, io_block_ptr,
io_block_len, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
io_block_ptr
Tolts area that contains the IO block to be sent. (See
Appendix A) (Input)
Note: The data_header_2 area will be nulled as well as data_2
the size will be set to 0. The data returned will be defined
by data_header_1 and the data returned in the data_1 area.
io_block_len
Size of tolts area in words. (See Appendix A) (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Notes
This entry must also be used to terminate a "maintenance
session". Refer to mca_$read_data for details.
____ ____
mca_ mca_
____ ____
Entry: mca_$tandd_write_data
This entry will allow the tolts subsystem to send previously
prepared IO blocks to the MCA. This entry will be used by tolts
to perform early communication with the MCA, prior to initiating
a test request, and to send TEST OVERLAY data to the MCA and to
maintain a response area for the MCA while a given test is being
executed. This entry will also move the IO block to a wired
area, replacing the IDCWs (15, 03) and DCWs with known good ones.
When the MCA returns response data, it will be copied from the
wired block into the user area and the MCA status returned to the
caller.
Usage
dcl mca_$tandd_write_data (fixed bin, ptr, fixed bin, bit (36),
fixed bin (35));
call mca_$tandd_write_data (mca_ioi_idx, io_block_ptr,
io_block_len, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
io_block_ptr
Tolts area that contains the IO block to be sent. (See
Appendix A) (Input)
io_block_len
Size of tolts area in words. (See Appendix A) (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Entry: mca_$tandd_write_text
This entry will allow the tolts subsystem to send previously
prepared IO blocks to the MCA. This entry must be used by tolts
to initiate a IO activity with the MCA, for a given IPC. This
entry will verify that the text portion of the block only
contains the valid commands READ, RESET, LOAD or TEST and that
the IPC attached is the only adapter specified after the command
text. This entry will also move the IO block to a wired area,
replacing the IDCWs (13, 03) and DCWs with known good ones. When
the MCA returns response data, it will be copied from the wired
block into the user area and the MCA status returned to the
caller.
Usage
dcl mca_$tandd_write_text (fixed bin, ptr, fixed bin, bit (36),
fixed bin (35));
call mca_$tandd_write_text (mca_ioi_idx, io_block_ptr,
io_block_len, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when the selected MCA was attached.
(Input)
io_block_ptr
Tolts area that contains the text IO block to be sent. (See
Appendix A) (Input)
io_block_len
Size of tolts area in words. (See Appendix A) (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the MCA is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
____ ____
mca_ mca_
____ ____
Notes
If the text of the I/O block specifies an IPC adapter, the
adapter must be attached to the user process. If the adapter is
not attached no I/O will be performed and an error code will be
returned.
_________ _________
mca_priv_ mca_priv_
_________ _________
Name: mca_priv_
Entry: mca_priv_$load_ipcs
This entry will allow all of the currently defined IPCs of the
selected IMU to have their internal firmware reloaded from the
MCA diskette and reset to a initialized state. This requires all
the IPCs of the IMU be attached to this process before this
command can be executed.
Usage
dcl mca_priv_$load_ipcs entry (fixed bin, bit (36),
fixed bin (35));
call mca_priv_$load_ipcs (mca_ioi_idx, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
_________ _________
mca_priv_ mca_priv_
_________ _________
Entry: mca_priv_$reset_ipcs
This entry will allow all of the currently defined IPCs of the
selected IMU to be reset to a initialized state. This requires
all the IPCs of the IMU be attached to this process before this
command can be executed.
Usage
dcl mca_priv_$reset_ipcs entry (fixed bin, bit (36),
fixed bin (35));
call mca_priv_$reset_ipcs (mca_ioi_idx, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
_________ _________
mca_priv_ mca_priv_
_________ _________
Entry: mca_priv_$force_reset
This entry will allow the user to reinitialize the MCA. This
entry issues a reset_mask PCW to the MCA. Executing this entry
has the same effect as pushing the "MCA Reset" button located in
the IMU cabinet.
Usage
dcl mca_priv_$force_reset (char (*), bit (36), fixed bin (35));
call mca_priv_$force_reset (mca_id, mca_status, code);
where:
mca_id
MCA name to be reset. The name must be in the form "mcaX",
where X will be equal to the letter of the IMU the MCA is in
(a, b, c, or d). (Input)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
code
Will be a standard system status code. (Output)
Notes
The MCA must be in the FREE state for this entry to operate
properly. The entry will attach the MCA, do the reset and detach
the MCA when complete.
_________ _________
mca_priv_ mca_priv_
_________ _________
Entry: mca_priv_$force_unlock
This entry will allow the per MCA lock in the ring-1 mca_data_seg
to be force unlocked.
Usage
dcl mca_priv_$force_unlock (char (*), fixed bin (35));
call mca_priv_$force_unlock (mca_id, code);
where:
mca_id
MCA name to be unlocked. The name must be in the form "mcaX",
where X will be equal to the letter of the IMU the MCA is in
(a, b, c, or d). (Input)
code
Will be a standard system status code. (Output)
_________ _________
mca_priv_ mca_priv_
_________ _________
Entry: mca_priv_$trace
This entry will allow the turning ON or OFF of the MCA console
messages (i.e. TRACING) displayed on the IPC-CONS adapter that
currently has the multidrop (MD) interface enabled.
Usage
dcl mca_priv_$trace entry (fixed bin, bit (3), bit (1),
char (40), bit (36), fixed bin (35));
call mca_priv_$trace (mca_ioi_idx, mca_option, on_off_bit,
trace_state, mca_status, code);
where:
mca_ioi_idx
IOI index value returned when MCA was attached. (Input)
mca_option
A three bit field that will define what MCA tracing types will
be affected by the call. The three types in order will be
FAULT, BOOT and DEBUG. (Input)
The values are: "100"b -> FAULT, "010"b -> BOOT, or "001"b ->
DEBUG. These values may be or'ed together.
on_off_bit
A one bit field that will define whether to turn the above
MCA_OPTIONS ON or OFF. "1"b = turn on tracing. "0"b turn off
tracing. (Input)
trace_state
This is the ascii data returned by the MCA to indicate the
state of tracing. (Output)
mca_status
This will be the status word returned by the MCA on completion
of the function. (Output)
This will only be valid when the mca is attached without
specifying an event channel to signal the completion of the
I/O (i.e. the mca_ module has gone blocked waiting for the
I/O to complete and is now returning status).
code
Will be a standard system status code. (Output)
MTB-663, Revision 3 MCA Online-Management
APPENDIX A: MCA_WORKSPACE
This is the definition of the workspace used by the mca ring-1
modules when communicating with the MCA through IOI. The
structure is declared in mca_data_area.incl.pl1.
dcl data_header_ptr ptr;
dcl (data_size_1, data_size_2) fixed bin (21) init (0);
dcl io_param_blk_ptr ptr;
dcl mca_dcw_list_ptr ptr;
dcl mca_work_space_ptr ptr;
dcl 1 mca_work_space based (mca_work_space_ptr),
2 list_of_dcw like mca_dcw_list,
/* the list of idcws and dcws */
2 status_area like istat,
/* the ioi status return area */
2 data_header_1 aligned like data_header,
/* the structure that defines the HOST to MCA data */
2 data_1 char (data_size_1),
/* the text of the data to be sent to the MCA */
2 data_header_2 aligned like data_header,
/* the structure that defines the MCA to HOST data */
2 data_2 char (data_size_2);
/* the text of the data returned by the MCA */
Note:
data_header_1 and data_1 areas are reserved for data TO the
MCA. The data_header_2 and data_2 areas are reserved for data
FROM the MCA. However if the "mca_$tandd_read_data" entry is
call the data will be returned in data_1 and defined in the
data_header_1 area. The data_header_2 values should be nulled.
MCA Online-Management MTB-663, Revision 3
dcl 1 data_header based (data_header_ptr) aligned,
2 type bit (9) unal,
/* must be equal to "000"b3 (MBZ) */
2 definer fixed bin (9) unal unsigned,
/* defines type of info in header */
2 ctl_sw bit (18) unal,
/* "currently undfined" mbz = "000000"b3 */
2 host_sts_ign1 bit (1) unal,
2 host_sts_msb bit (8) unal,
2 host_sts_ign2 bit (1) unal,
2 host_sts_lsb bit (8) unal,
2 rd_flpy fixed bin (9) unal unsigned,
/* 0 = data files from host */
/* 1 = data files from flopy */
2 io_param_blk like io_parameter_block unal;
MTB-663, Revision 3 MCA Online-Management
dcl 1 io_parameter_block based (io_param_blk_ptr) unal,
2 open fixed bin (9) unal unsigned,
2 cmd bit (18),
2 sts_ptr bit (18),
/* Unused */
2 file_name char (8),
/* file name for this request */
2 options bit (18),
/* Unused */
2 source_ptr bit (18),
/* Unused */
2 source_len,
/* data_size =
source_len_msb||source_len_lsb MCA to HOST */
3 source_len_ign1 bit (1),
3 source_len_msb bit (8),
3 source_len_ign2 bit (1),
3 source_len_lsb bit (8),
2 dest_ptr bit (18),
/* Unused */
2 blk_ct,
/* if MCA to HOST blk_ct_msb||blk_ct_lsb =
MAX number of 256 byte BLOCKS */
/* else not used */
3 blk_ct_ign1 bit (1),
3 blk_ct_msb bit (8),
3 blk_ct_ign2 bit (1),
3 blk_ct_lsb bit (8),
2 dest_len,
/* supplied by host as the number of bytes
in data_field max value is 16128 */
/* dest_len_msb = substr(unspec(data_size),21,8) */
/* dest_len_lsb = substr(unspec(data_size),29,8) */
3 dest_len_ign1 bit (1),
3 dest_len_msb bit (8),
3 dest_len_ign2 bit (1),
3 dest_len_lsb bit (8);
/* Constants used for data_header.definer */
MCA Online-Management MTB-663, Revision 3
dcl DATA_FROM_HOST
fixed bin (9) unsigned init (0) static options (constant);
dcl WRITE_CONSOLE
fixed bin (9) unsigned init (1) static options (constant);
dcl WRITE_READ_CONSOLE
fixed bin (9) unsigned init (2) static options (constant);
dcl DATA_FROM_MCA
fixed bin (9) unsigned init (3) static options (constant);
dcl REQ_DATA_FROM_HOST
fixed bin (9) unsigned init (4) static options (constant);
dcl STATUS_FROM_MCA
fixed bin (9) unsigned init (5) static options (constant);
dcl SEEK
fixed bin (9) unsigned init (6) static options (constant);
dcl CON_DATA_FROM_HOST
fixed bin (9) unsigned init (7) static options (constant);
dcl BIN_DATA_FROM_HOST
fixed bin (9) unsigned init (8) static options (constant);
dcl ABORT_SES_FROM_HOST
fixed bin (9) unsigned init (9) static options (constant);
dcl 1 mca_dcw_list based (mca_dcw_list_ptr),
2 idcw1 like idcw,
2 dcw1 like dcw,
2 idcw2 like idcw,
2 dcw2 like dcw;
dcl 1 dcw based (dcwp) aligned,
/* Data Control Word */
(2 address bit (18),
/* address for data transfer */
2 char_pos bit (3),
/* character position */
2 m64 bit (1),
/* non-zero for mod 64 address */
2 type bit (2),
/* DCW type */
2 tally bit (12)) unal;
/* tally for data transfer */
MTB-663, Revision 3 MCA Online-Management
dcl 1 idcw based aligned,
/* Instruction DCW */
(2 command bit (6),
/* device command */
2 device bit (6),
/* device code */
2 ext bit (6),
/* address extension */
2 code bit (3),
/* should be "111"b for PCW */
2 ext_ctl bit (1),
/* "1"b if address extension to be used */
2 control bit (2),
/* terminate/proceed and marker control bits */
2 chan_cmd bit (6),
/* type of I/O operation */
2 count bit (6)) unal
/* record count or control character */;
dcl 1 istat based aligned,
/* I/O Interfacer status structure */
2 completion,
/* completion flags */
(3 st bit (1),
/* "1"b if status returned */
3 er bit (1),
/* "1"b if status indicates error condition */
3 run bit (1),
/* "1"b if channel still running */
3 time_out bit (1)) unal,
/* "1"b if time-out occurred */
2 level fixed bin (3),
/* IOM interrupt level */
2 offset fixed bin (18),
/* DCW list offset */
2 absaddr fixed bin (24),
/* absolute address of workspace */
2 iom_stat bit (72),
/* IOM status */
2 lpw bit (72)
/* LPW residue */;
MCA Online-Management MTB-663, Revision 3
APPENDIX B: MCA_CONFIG_FILE
The following structure was built based on data obtained from the
EPS-1 "Dipper Firmware Loading" Rev B section 3.5.1 starting on
sheet 25. The structure is declared in mca_config_file.incl.pl1.
dcl mca_config_file_ptr ptr;
dcl 1 mca_config_file based (mca_config_file_ptr),
2 diskette_data,
/* total of 20 chars (bytes) */
3 unique_id char (8),
/* User ID assiged to diskette from witch FW was loaded */
3 date_created char (6),
/* MMDDYY */
3 date_late_changed char (6),
/* MMDDYY */
2 iioc_data,
/* total of 31 chars (bytes) */
3 iioc_config char (8),
/* mca path_name of file used to load from */
3 iioc_state_control,
4 will_be_zero_1 bit (1),
/* zero because of 8 bit-byte to 9 bit-byte */
4 state_counter fixed bin (5) unsigned unal,
/* values are not defined */
4 RFU_1 bit (1),
4 RFU_2 bit (1),
4 write_protect_ptw_sw bit (1),
3 operating_system fixed bin (9) unal unsigned,
/* better be a value equal to Multics */
3 iioc_num fixed bin (9) unal unsigned,
/* the number of the imu */
3 iioc_disk_tab fixed bin (9) unal unsigned,
/* The value of the TAB number of the Diskette_Product_Set
containing the proper revision of diagnostics for IMU */
3 p_s_disk_tab fixed bin (9) unal unsigned,
/* same as iioc_disk_tab only for the Port Select */
3 port_select_state fixed bin (9) unal unsigned,
/* State counter values will exists which uniquely define:
o P. S. not loaded
o Single port
o Load failed
o Read failed
o Verify failed
o P. S. loaded */
3 config_valid char (1),
/* ascii number of drive this config was read from.
if value = "000"b3 drive door has been opened. */
3 iioc_rfu char (2),
2 bootstrap_data,
/* total of 15 chars (bytes) */
MTB-663, Revision 3 MCA Online-Management
3 control fixed bin (9) unal unsigned,
/* 0 = bootstrap not configured
1 = bootstrap allowed
2 = auto boot at power up */
3 imu_port_at_scu fixed bin (9) unal unsigned,
/* port number for bootstrap (0 to 7) */
3 chan_num fixed bin (9) unal unsigned,
/* bootstrap channel number (8 to 63) */
3 dev_num fixed bin (9) unal unsigned,
/* bootstrap device number (1 to 63) */
3 int_base char (4),
3 mb_base char (4),
3 boot_src fixed bin (9) unal unsigned,
/* bootstrap source 1=card, 2=tape, 3=disk */
3 unatt_op fixed bin (9) unal unsigned,
/* 1 = unattended operation */
3 boot_rfu bit (9),
2 port_data (0:3),
/* total 28 chars (bytes) */
3 enable fixed bin (9) unal unsigned,
/* 1 = port enable */
3 init fixed bin (9) unal unsigned,
/* 1 = init allowed */
3 ilace char (1),
/* no interlace = "000"b3,
A,B,C,D = the other port for interlace */
3 port_size,
4 msb_ign1 bit (1),
4 msb bit (8),
4 lsb_ign1 bit (1),
4 lsb bit (8),
3 disk_tab fixed bin (9) unal unsigned,
/* value of TAB number of the D_P_S containing the proper
revision of diagnostics for port adapter. */
3 assignment fixed bin (9) unal unsigned,
/* (0 - 3) */
2 channel_data (0:15),
/* total of 160 bytes */
3 lvl_1_state fixed bin (9) unal unsigned,
/* State counter values define:
= No config present
= Not configured
= Phyically not present
= Basic ROM test failed (mico IPCs only)
= Jam test failed (mico IPCs only)
= Self test failed (mico IPCs only)
= HW ID does not match config ID
= Console set up failed (console only)
= RSO failed (PSIA only)
= FW not found on diskette (FW loadable IPCS only)
= Alter file not found
= Alter load failed
MCA Online-Management MTB-663, Revision 3
= FW execute failed (FW loadable IPCS only)
= Operational
= Stop On condition occured */
3 lvl_1_ctl_att,
4 ctl_ign1 bit (1),
4 ctl1 bit (1),
/* if master console true = rmt_maint
else true = RSO required at init */
4 ctl2 bit (1),
/* if master console true = master
else reserved of future use */
4 ctl3 bit (1),
/* if master console true = active/slave
else true = 18X */
4 ctl_p2 bit (5),
3 disk_tab fixed bin (9) unal unsigned,
/* Tab number of the D_P_S containing the proper
revision of diagnostics for this adapter */
3 fw_id_ign1 bit (1),
3 fw_id bit (8),
3 lvl_1_id_ign1 bit (1),
3 no_lev_2 bit (1),
/* true = Do not ask for lvl-2 info. */
3 micro_ctl bit (1),
/* true = micro-procesor controled */
3 fbus_latch bit (1),
/* true = F-Bus Disable Latch is true */
3 lvl_1_id_type fixed bin (5) unsigned unal,
/* unique Lvl-1 type */
3 fw_rev char (1),
3 prim_ch_num fixed bin (9) unal unsigned,
/* primary channel number (8 to 63) */
3 num_of_log_ch fixed bin (9) unal unsigned,
/* number of logical channels */
3 num_of_busses fixed bin (9) unal unsigned,
/* number of data busses */
3 cont_byte_ign1 bit (1),
3 cont_byte_rfu bit (5),
3 cont_byte_soc bit (1),
/* true = Stop-On-Condition present */
3 cont_byte_mpfp bit (1),
/* true = maint. panel fuction present */
3 cont_byte_mc bit (1),
/* true = has been set to Master Console */
2 adapter_data (0:15, 0:7),
3 lvl_2_state fixed bin (9) unal unsigned,
3 lvl_2_clt_att fixed bin (9) unal unsigned,
3 disk_tab fixed bin (9) unal unsigned,
3 fw_idfixed bin (9) unal unsigned,
3 lvl_2_id fixed bin (9) unal unsigned,
3 fw_rev_ign1 bit (1),
3 fw_rev bit (8),
MTB-663, Revision 3 MCA Online-Management
3 rfu bit (1),
2 uses_less_data char (200);
MCA Online-Management MTB-663, Revision 3
APPENDIX C: MCA_AREA
MCA Area Structure:
The mca_area_ptr points to a structure which defines the format
of the data filled in by the mca_ module when I/O between the
attached MCA and Multics has completed. This area is only used
when the user has specified an event channel to be notified
through. The structure is declared in mca_area.incl.pl1.
dcl 1 mca_area aligned based (mca_area_ptr),
2 version char (8),
2 io_outstanding bit (1) aligned,
2 mca_attach_state fixed bin (17),
2 mca_status bit (72),
2 ret_len fixed bin (21);
dcl mca_area_ptr ptr;
dcl MCA_area_version_1 char (8) int static options
(constant) init ("MCA00001");
where:
version
Is the version number of the structure. The current version
is MCA00001.
io_outstanding
This will indicate the status of the maintenance session.
Will be false if the requested task has been completed. If
true, the task is not complete and the user will be required
to call this entry again upon completion of the next I/O.
mca_attach_state
This will contain the current attachment state. 1 =
"Attaching", which means that the mca modules are still in the
process of attaching the mca (doing the reset & read-config
IO). 2 = "Attached", which means that the mca is now fully
attached.
mca_status
Is the status returned by the MCA upon completion of the
request.
ret_len
Is the number of characters placed in the user area.
MTB-663, Revision 3 MCA Online-Management
APPENDIX D: MCA_DATA_SEG
This is the format of the ring_1 MCA control segment. It is
created by mca_init_ in ring_1. The structure is declared in
mca_data.incl.pl1.
dcl mca_data_seg$ ext;
dcl MCA_data_version_1 char (8) int static options
(constant) init ("MCA00001");
dcl mca_data_seg_ptr ptr;
dcl mcad_ptr ptr;
dcl ipcd_ptr ptr;
The data segment is an array of four data structures, one for
each possible IMU that can be configured on the system.
dcl 1 mca_data_seg based (mca_data_seg_ptr),
2 array (1:4) like mcad;
The following structure is the format for each array element.
dcl 1 mcad based (mcad_ptr) aligned,
2 lock bit (36),
/* The mca write lock. */
2 state fixed bin,
/* Current mca state */
2 attach_time fixed bin (71),
/* DT/time of attach */
2 attach_pid bit (36),
/* PID of attaching process */
2 name char (1),
/* name of this mca (a b c d) */
2 imu_number fixed bin (17),
/* number of the IMU */
2 ioi_idx fixed bin,
/* value to use with ioi_ */
2 event_chn fixed bin (71),
/* ipc channel for IO processing ring_1 */
2 ioi_wks_ptr ptr,
/* pointer to IOI Workspace */
2 max_ws_size fixed bin (19),
2 user_ptr ptr,
/* used for async_io */
2 return_data_ptr ptr,
/* user for async_io */
2 io_param_ptr ptr,
/* pointer to the io_parameter_block
for mca returned data */
MCA Online-Management MTB-663, Revision 3
2 entry_to_return_data entry
(ptr, fixed bin (21), fixed bin (35)),
/* entry that will return the data
to the user for async_io */
2 status_offset fixed bin,
/* offset into work space for status */
2 current_ws_size fixed bin (19),
/* current work_space */
2 rcp_id bit (36),
2 flags unaligned,
3 async_io bit (1),
/* 1 = outer ring will catch IO events */
/* 0 = ring 1 will go blocked and wait
for IO to complete */
3 config_data_requested bit (1),
/* used during mca attachment */
3 pad bit (34),
2 max_time_out fixed bin (71),
/* maximum time for time out */
2 last_status bit (71),
/* most recent MCA status return */
2 ipcd_array (0:15) like ipcd aligned;
The ipc_array elements are initiated when the MCA is attached to
a users process. Most of the data used is extracted from the
internal MCA config file. At attach time this config file is
read from the MCA and the mca_util_$fill_config_data entry
(ring_1) copys the selected data from this file into the correct
ipc_array element. The data in the mca_config file must be
converted from 8 bit bytes to the Multics 9 bit bytes.
dcl 1 ipcd based (ipcd_ptr) aligned,
2 ipc_name char (8),
/* "ipcXX" */
2 channel fixed bin,
/* base channel */
2 nchan fixed bin,
/* number of channels */
2 type_info,
/* type of IPC */
3 no_level_2_info bit (1),
3 is_micro_cont bit (1),
3 fbus_disable_latch bit (1),
3 pad bit (6) unaligned,
3 type_index fixed bin,
2 state fixed bin (17) unaligned,
/* current state */
2 level_1_state fixed bin,
/* LVL-1_STATE */
2 prph_attachments fixed bin (17),
MTB-663, Revision 3 MCA Online-Management
/* # of RCP attachments */
2 attach_data (8),
3 prph_name char (4),
/* Multics prph name */
3 flags unaligned,
4 attached_thru_rcp bit (1),
/* must detach when done */
4 io_suspended bit (1),
/* must resume IO when done */
4 pad (34) bit (1),
3 attach_time fixed bin (71),
/* DT/time of attach */
3 ipc_rcp_id bit (36),
/* rcp id */
3 ipc_ioi_idx fixed bin;
/* index from rcp */
dcl SYSTEM_DIR char (17)
init (">system_library_1") static options (constant);
dcl DATA_SEG char (12)
init ("mca_data_seg") static options (constant);
/* possible mcad.state values */
dcl (MCA_NOT_CONFIGURED init (0),
MCA_FREE init (1),
MCA_ATTACHING init (2),
MCA_ATTACHED init (3),
MAINT_SESSION init (10))
fixed bin internal static options (constant);
/* possible ipcd.state values */
dcl (IPC_NOT_CONFIGURED init (0),
IPC_FREE init (1),
IPC_ATTACHED init (2))
fixed bin internal static options (constant);
MCA Online-Management MTB-663, Revision 3
APPENDIX E: MCA_DISKETTE
This is the definition of the data returned by the MCA when
either reading the diskette header, directory or files. The
structure is declared in mca_diskette.incl.pl1.
dcl header_ptr ptr;
dcl 1 header based (header_ptr),
2 copyright char (55),
2 title char (8),
2 unique_id char (8),
2 date_created char (6),
2 date_changed char (6),
2 space_adr bit (18) unal,
2 space_x bit (18) unal,
2 space_size bit (18) unal,
2 dir_adr bit (18) unal,
2 dir_x bit (18) unal,
2 dir_size like two_byte,
2 config_name char (8),
2 config_count fixed bin (9) unal unsigned,
2 disk_type fixed bin (9) unal unsigned,
2 val fixed bin (9) unal unsigned,
2 equip_type char (4),
2 ipi_num char (12),
2 disk_dwg_num char (12),
2 prod_num_tab char (3),
2 x_of_n bit (18) unal;
dcl dir_ptr ptr;
dcl dire_ptr ptr;
dcl dir_number fixed bin;
dcl 1 directory based (dir_ptr),
2 array (dir_number) like dire;
dcl two_byte_ptr ptr;
dcl 1 two_byte based (two_byte_ptr) unal,
2 pad1 bit (1) unal,
2 lsb bit (8) unal,
2 pad2 bit (1) unal,
2 msb bit (8) unal;
dcl 1 dire based (dire_ptr),
2 path_name char (8),
2 sector_address like two_byte,
2 file_size like two_byte,
2 rfu like two_byte,
2 attributes bit (8) unal,
MTB-663, Revision 3 MCA Online-Management
2 deleted bit (1) unal,
2 rfu1 char (1);
dcl file_ptr ptr;
dcl file_size fixed bin (21);
dcl 1 hex_file based (file_ptr),
2 hex_data (file_size) like two_byte;
MCA Online-Management MTB-663, Revision 3
APPENDIX F: MCA_RETURN_STATUS
Status Major Substatus Octal
Channel Ready 0000
Normal Termination x00000 4000 or 4040
Adapter Failure x00001 4001 or 4041
Maint. Session Normal Term. x00010 4002 or 4042
Maint. Session Abnormal Term. x00011 4003 or 4043
Response Data Present 1xxxxx *
Attention (Diskette) 0010
Write Inhibit x00001 4201 or 4241
Seek Incomplete x00010 4202 or 4242
Device Not Present x00100 4204 or 4244
Device Inoperable x01000 4210 or 4250
Device in Standby (door open) x10000 4220 or 4260
Data Alert 0011
Transmission Parity Alert x00010 4302 or 4342
Check Character Alert x10000 4320 or 4360
Command Reject 0101
Invalid Operation Code x00001 4501 or 4541
Attention (MCA) 1010
MCA Executive F/W Error x00001 5201 or 5241
MCA Overlay F/W Error x00010 5202 or 5242
Connect Time Out x10000 5220 or 5260
Data Alert (MCA) 1011
Data Overflow on Load x00110 5306 or 5346
Data Underflow on Load x00111 5307 or 5347
Command Reject (MCA) 1101
Invalid Sequence x00001 5501 or 5541
Invalid PATH_NAME x00010 5502 or 5542
Invalid Request Format x00011 5503 or 5543
Continue Bit Error x00100 5504 or 5544
Invalid Block Header x00101 5505 or 5545
* The Response Data Present bit is applicable to ALL status returns.