DPI Program Channel

A Program Channel is a standard channel type according to the description in “Standardized General Purpose Channel Types” issued by the International P-NET User Organization. The function of such a channel is to provide a mechanism for downloading programs and to monitor and control the status and the memory type and location of each. A number of programs may be held and selected from a library.

A 600 series DPI has two Program Channels, channel 5 and channel 6. Channel 5 is called OpSysCh (Operating System Program Channel) and Channel 6 is called PPprogCh (Process-Pascal Program Channel).

The Operating System Program Channel provides the ability to download and run the operating system in the DPI. The operating system is split up into a boot system (named PROM) and a normal system (named FLASH). On delivery, the boot operating system will have already been downloaded to the DPI. A full (normal) operating system can be downloaded using this channel. During download of the full operating system, the boot operating system will be running. The boot operating system only provides the necessary functionality to download the normal operating system. It holds no Process-Pascal interpreter, so the DPI is unable to run a Process-Pascal program until the normal operating system is downloaded and running.

The Process-Pascal program channel provides the ability to download and run Process-Pascal programs in the DPI. The program can be downloaded to the FLASH memory. The FLASH operating system also holds a Process-Pascal program, containing the global variables needed for downloading.

If a Process-Pascal program causing a reset of the device is downloaded, it may be impossible to re-establish any contact with the device. To work around this problem, the following functionality applies:

Following a MasterReset, the boot operating system is running, and the Process-Pascal is not running. After a normal reset, the device again uses the configuration selected.

Program channel structure

RegNo.	Identifier	Memory type	Read out	Type
0	ProgramControl	RAM ReadWrite	--------	Record
1	ProgramStatus	RAM ReadOnly	--------	Record
2	ProgramID	PROM ReadOnly	--------	Record
3
4
5
6
7	MemoryInfo	RAM ReadOnly	--------	Record
8	IDAndCode	PROM ReadOnly	--------	Record
9	ChConfig	EEPROM RPW	--------	Record
10	LibraryControl	RAM ReadWrite	--------	Record
11	LibraryStatus	RAM ReadOnly	--------	Record
12	LibraryProgramID	PROM ReadOnly	--------	Record
13	Maintenance	EEPROM RPW	--------	Record
14	ChType	PROM ReadOnly	--------	Record
15	ChError	RAM ReadOnly	--------	Record

RegNo. 0: ProgramControl

This variable is a record having the following structure:

Record
	Command:	Byte;
	ProgramToSelect:	Word;
	ErrorStatus:	Bit32;
End;

ProgramControl is used to set and change the state of the current program, which has been selected and invoked via the Program Channel. The selected program number is inserted and indicated as a part of ProgramControl. Commands can be sent to ProgramControl to stop, start or Reset the program.

Command is used to send a command to the Program Channel to change the state of the current program. A list of possible commands is given below. The commands and the corresponding numbers conform to the Request Instructions used by MMS.

	Command	Purpose
	38 SelectProgram	Selects a program from the library, resulting in State = Idle. (MMS = CreateProgramInvocation)
	39 UnSelectProgram	Sets SelectedProgram to 0, resulting in State changing to Non-selected. (MMS =DeleteProgramInvocation)
	40 Start	Starts the selected program (MMS = Start) if the program is OK.
	41 Stop	Stops the selected program. (MMS = Stop)
	42 Resume	Continues program execution in the selected program. (MMS = Resume)
	43 Reset	Resets the selected program. (MMS = Reset)
	44 Kill	Stops the selected program instantly and sets the state to unrunable. (MMS = Kill)

The Program Channel automatically sets Command to 0 after writing to the variable. State is updated immediately to one of the corresponding temporary states, Starting, Stopping, Resuming or Resetting each time a command is sent to the Command variable. By the change in state, it is possible to read the variable ProgramStatus.State to check whether the Command was executed successfully or that the operation failed.

ProgramToSelect holds the library index for the program to select or the already selected program. ProgramToSelect is copied from ChConfig following a device Reset or power up. It can hold the values 1 for boot (PROM) or 2 for normal (normal).

ErrorStatus indicates each type of error in a program by means of a Boolean value. An error may be cleared in this register by writing False to the corresponding error bit. The ErrorStatus indicates run-time errors in the running operating system.

RegNo. 1: ProgramStatus

This variable is a record having the following structure:

Record
	State:	Byte;
	SelectedProgram:	Word;
	ErrorStatus:	Bit32;
End;

ProgramStatus summarises the state and error condition of the selected program. The library index for the selected program is also indicated.

State indicates the current state of the selected program, e.g. stopping, stopped, running, idle, non-selected etc. A state diagram and a list of possible states are given below. The states and the corresponding numbers conform to the states for Program Invocation Management used by MMS.

State	Explanation
0 Non-selected	No program selected. (MMS = Non-selected)
1 Unrunable	The program cannot run. (MMS = Unrunable)
2 Idle	The program is stopped and Reset. (MMS = Idle)
3 Running	The program is running. (MMS = Running)
4 Stopped	The program is stopped. (MMS = Stopped)
5 Starting	The program is changing state from idle to running. (MMS = Starting)
6 Stopping	The program is changing state from running to stopping. (MMS = Stopping)
7 Resuming	The program is changing state from stopped to running. (MMS = Resuming)
8 Resetting	The program is changing state from stopped to idle. (MMS = Resetting)

SelectedProgram holds the library index for the selected program. SelectedProgram is 0 if State is Non-selected.

ErrorStatus is identical to ProgramControl.ErrorStatus, but only read access is possible.

RegNo. 2: ProgramID

This variable is a record having the following structure:

Record
	ProgramName:	String[20];
	Version:	Word;
	InterpreterVers:	Word;
	SoftwareHouse:	String[20];
	CompileTime:	DateTimeRec;
	CompilerVersion:	Word;
	ActualSize:	LongInteger;
	SumCheck:	Word;
	CodeType:	Word;
	NoOfTask:	Word;
	RAMNeed:	LongInteger;
	DataFlashNeed:	LongInteger;
End;

ProgramID is used to identify the selected program. The record includes a name for the program, version number, the required version number for the interpreter program and a name for the Softwarehouse that created the program. Compile time, compiler version and actual size for the program is also a part of ProgramID as well as SumCheck (two complement word addition without carry) and a code type identifier. The SumCheck value may be used for check sum calculations when the program is selected, i.e. following a SelectProgram command (38). CodeType must match CodeType found in ChType.

The International P‑NET User Organization specifies the values and interpretation for CodeType. This description is available in a separate document, No. 590 003 and may be obtained on request.

RegNo. 7: MemoryInfo

This variable is a record having the following structure:

Record
	ActualSize:	LongInteger;
	MaxSize:	LongInteger;
	MemoryType:	Word;
	RAMSize:	LongInteger;
	DataFlashSize:	LongInteger;
End;

For each program segment, selected by LibraryControl.LibraryIndex, a corresponding memory information can be read. The memory information holds the actual size for the program, the max. size for the program segment and a code for the memory type in which the program is stored. Finally, MemoryInfo holds information of the available amount of RAM and FLASH memory for data.

ActualSizeincludes the size of the program code and the header with the ProgramID.

MaxSizeindicates the max size for the program segment and is the max size for a program to download within the memory area specified by MemoryType.

The International P‑NET User Organisation specifies the values and interpretation for MemoryType. This description is available in a separate document, No. 590 003 and may be obtained on request.

RAMSize indicates the amount of RAM available for the program. A Process-Pascal program needs RAM for as well global as local variables, stack and task information. If a program requiring more RAM than indicated by RAMSize is downloaded to a DPI, the program can’t run, and the state of the program will be “Unrunable”.

DataFlashSize indicates the amount of data FLASH available for the program. A Process-Pascal program needs data FLASH for global variables declared as placed in FLASH. If a program requiring more data FLASH than indicated by DataFlashSize is downloaded to a DPI, the program can’t run, and the state of the program will be “Unrunable”.

RegNo. 8: IDAndCode

IDAndCode:

Array[1..ActualSize] Of Byte;

This variable is used for download of programs to the Program Channel. When a program is downloaded to the Program Channel, the entire program and a header with the ProgramID and size indicator is stored in IDAndCode by means of a LongStore instruction.

The format for the data stored in the first part of IDAndCode exactly matches the format for ProgramID, and IDAndCode is interpreted as a record of the following type:

Record
	ProgramName:	String[20];
	Version:	Word;
	InterpreterVers:	Word;
	SoftwareHouse:	String[20];
	CompileTime:	DateTimeRec;
	CompilerVersion:	Word;
	ActualSize:	LongInteger;
	SumCheck:	Word;
	CodeType:	Word;
	NoOfTask:	Word;
	RAMNeed:	LongInteger;
	DataFlashNeed:	LongInteger;
	Reserved2:	LongInteger;
	ProgramCode:	Array[1..(ActualSize-HeaderSize)] Of Byte;
End;

Before the program can be downloaded to the channel, the download program must ensure that:

· The necessary memory is available, as well for the program itself, as for RAM and FLASH variables.

· The code-type for the program code is in accordance with the code-type specified for the channel.

· The interpreter program in the operating system is of the right version.

To download a program, the corresponding command must be sent to LibraryControl.Command register to initiate the sequence. The download program must wait for LibraryStatus.State = Loading before the download is executed.

ActualSize for a program is given in LibraryProgramID.ActualSize after a complete download.

RegNo. 9: ChConfig

This variable is a record having the following structure:

ChConfig: Record		(* Factory setting *)
	EnableBit:	Bit8;	(* 00000001 *)
	Functions:	Byte;	(* 0 *)
	Ref_A:	Byte;	(* 1 *)
	Ref_B:	Byte;	(* 0 *)
End;

The specification for how the selected program should operate after a Reset or power failure is held in ChConfig. This configuration includes a number specifying which program should be invoked after a Reset.

For OpSysCh, EnableBit is not used.

For PPprogCh, Enablebit[0] indicates how the selected program should operate after a power failure or device Reset.

Enablebit[0] = True indicates that the selected program must perform an autostart, resulting in State = Running. This is the default behaviour.

Enablebit[0] = False indicates that the selected program must not autostart, but must go to State = Idle.

Enablebit[1] indicates how the selected program should operate after a device Reset caused by an error, such as Watchdog, Bus Error etc.

Enablebit[1] = True indicates that the selected program must operate as selected by Enablebit[0].

Enablebit[1] = False indicates that the selected program should not autostart, although Enablebit[0] is True. This is the default behaviour.

Functions is not used.

For OpSysCh, Ref_A holds the selected program number, which should be invoked after a device Reset or power up. If Ref_A = 0, it is automatically changed to 1, selecting boot (PROM). Regardless of the value of Ref_A, the boot operating system is invoked after a master reset.

For PPprogCh, Ref_A holds the selected program number to be invoked following a device Reset or power up. If Ref_A = 0, 1 is automatically inserted, selecting PROM. Regardless of the value of Ref_A, no Process-Pascal program is invoked after a master reset.

Ref_B is not used.

RegNo. 10: LibraryControl

This variable is a record having the following structure:

Record
	Command:	Byte;
	LibraryIndex:	Word;
End;

LibraryControl is used to set and change the state of a program in the library. The program in the library is chosen with LibraryIndex. Commands can be sent to LibraryControl to control a download sequence.

Command is used to send a command to the Program Channel for changing the state of the program chosen by LibraryIndex. A list of possible commands is given below. The commands and the corresponding numbers conform to the Request Instructions for download used by (MMS).

Command	Purpose
26 InitiateDownloadSequence	Prepare for download. (MMS = InitiateDownloadSequence)
28 TerminateDownloadSequence	Cancel download and end sequence. (MMS = TerminateDownloadSequence)
36 DeleteProgram	Delete program from the library. (MMS = DeleteProgram)

The Program Channel automatically sets Command to 0 after writing to the variable. State is immediately updated to one of the corresponding temporary states, Complete or Incomplete each time a command is sent to the Command variable. By the change in state, it is possible to read the variable LibraryStatus.State, to check if the Command was executed successfully or the operation failed.

LibraryIndex chooses one of the programs in the program library. When a program is chosen, all data concerning this program may be accessed. The data for the chosen program may be read in the variables LibraryProgramID, LibraryStatus and MemoryInfo. Upload and download of the complete program, including the program code, is performed via the IDAndCode variable.

If LibraryIndex is equal to ProgramStatus.SelectedProgram, download is not possible.

The value of LibraryIndex must be 1 or 2.

RegNo. 11: LibraryStatus

This variable is a record having the following structure:

Record
	State:	Byte;
	LibraryIndex:	Word;
	MaxLibraryIndex:	Word;
End;

LibraryStatus is used to read the current state for a program in the library. LibraryIndex indicates the chosen program in the library. MaxLibraryIndex states the max. number of programmes in the library.

State indicates the current state for the program, e.g. loading, ready, nonexistent etc. A list of possible states is given below. The states and the corresponding numbers conform exactly to the states for download domain used by The Manufacturing Message Specification.

State	Explanation
0 Non-existent	No program in this memory type or program segment. (MMS = Non-existent)
1 Loading	Download in progress. (MMS = Loading)
2 Ready	The program is ready to be selected to run. (MMS = Ready)
3 In-use	This program is selected in ProgramControl. The state change to/from In-use is entirely controlled in ProgramControl. Download is not allowed. (MMS = In-use)
4 Complete	The program is completely downloaded and will change state to ready. (MMS = Complete)
5 Incomplete	An error has occurred during download and the program changes state to Non-existent. (MMS = Incomplete)
14 Deleting	Deletion in progress, e.g. clearing Flash. (MMS = Deleting)

LibraryIndex is identical to LibraryControl.LibraryIndex.

MaxLibraryIndex indicates the max. number of programs which can be, or are stored in the program channel. This value includes the number of programs and available program segments. The manufacturer determines how the program memory is managed when downloading and deleting programmes in the program library, and assessing what value MaxLibraryIndex is set to. The hardware in the programmable device and the Program Invocation Management defines the total number of programs to access and select.

There are 2 types of memory - boot and normal, and 1 program for each memory type, giving MaxLibraryIndex = 2.

RegNo. 12: LibraryProgramID

LibraryProgramID corresponds completely with ProgramID, but is used to identify the program in the program library.

A number, LibraryIndex, which is found in LibraryControl, chooses a program from the library.

LibraryProgramID is a record of the same type as ProgramID.

RegNo. 13: Maintenance

This variable is a record having the following structure:

Record
	Date:	Byte;	(* Offset = 0 *)
	Month:	Byte;	(* Offset = 1 *)
	Year:	Byte;	(* Offset = 2 *)
	Category:	Byte;	(* Offset = 3 *)
End;

The Maintenance variable is used for service management and maintenance purposes, and holds the last date of service and an indication of the type of service.

RegNo. 14: ChType

This variable is a record having the following structure:

Record
	ChannelType:	Word;
	Exist:	Bit16;
	InterpreterVers:	Word;
	CodeType:	Word;
End;

For the Program Channel, ChType has the following values:

ChannelType = 11

Exist =

Bit no	15								7							0
Value	1	1	1	1	1	1	1	1	1	0	0	0	0	1	1	1

InterpreterVers indicates the version of the interpreter, and in PPprogCh, has the value 400 (version 4.00).

CodeType indicates which kind of program code can be executed in the Program Channel. For the OpSysChan, this will have the value of 6 (meaning Motorola Coldfire machine code).

For the PPprogCh, this will have the value 4 (meaning Process-Pascal).

RegNo. 15: CHError

This variable is a record having the following structure:

Record
	His:	Bit8;	(* Offset = 0 *)
	Act:	Bit8;	(* Offset = 2 *)
End;

ChError for Operating System Program Channel and Process-Pascal program Channel

0: Buffer error (PPProgCh only)

1: Arithmetic error (PPProgCh only)

2: Index error (PPProgCh only)

3: Other error (PPProgCh only)

4: Not enough FLASH (PPProgCh only)

5: Not enough RAM (PPProgCh. only)

6: Program checksum error (.His only)

7: Device error

Bit 7	Device error. If this bit is set, the rest of the bits have no meaning because a device error can cause random error codes on the individual channels (see also "Service channel").
Bit 6	Program checksum error. This bit is set if an attempt to start the operating system in FLASH failed, because of a checksum error in that program. The operating system in PROM will be automatically started instead. This error is only set in ChError.His.
Bit 5	Not enough RAM error is generated when a Process-Pascal program requiring more RAM than available, is attempting to start. Downloading a Process-Pascal program requiring less RAM clears the error.
Bit 4	Not enough FLASH error is generated when a Process-Pascal program requiring more FLASH for data than available, is attempting to start. Downloading a Process-Pascal program requiring less FLASH for data clears the error.
Bit 3	Other error is generated for example as a result of a conversion error related to the Display or Update P-Codes. The error can also be generated when a Process-Pascal instruction, which is not implemented in the device, is used. If this error occurs, the Process-Pascal program stops immediately. To resume, go into the download utility in VIGO, un-select “Autostart after reset”, reset the DPI, and download a program without the error.
Bit 2	Index error is generated when a Process-Pascal program is trying to access an element in an array with an index out of the array bounds.
Bit 1	Arithmetic error is generated when a Process-Pascal program is performing an operation resulting in an arithmetic error, for example division by zero.
Bit 0	Buffer error is generated when a Process-Pascal program is trying to load from an empty buffer, or store to a full buffer.