hpoj reference: ptal-mlcd

Currently, ptal-mlcd performs parallel-port I/O by accessing the hardware registers and performing the IEEE 1284 ECP- and nibble-mode signalling directly from user mode, with no kernel or accelerated hardware assistance. On the other hand, USB support depends on kernel printer-class device support.

In addition to this document, please refer to the instructions for setting up basic device connectivity for more information on ptal-mlcd.

Syntax

	ptal-mlcd bus:name [options...]

• bus is the connection type and is one of:
  • par -- Parallel port
  • usb -- Universal Serial Bus
• name is the desired name or number suffix for this device
• Common options for all bus types:
  • -remconsole -- Enables remote debug console (service name PTAL-MLCD-CONSOLE, socket -1)
• Less common options for all bus types:
  • -nofork -- Stays in the foreground, enables local console
  • -hotplug -- Activates at startup, exits on failure
  • -alias name2 -- Creates alias for bus:name (for example, mlcpp0, to help migrate from earlier hpoj versions)
  • -nodot4 -- Disables 1284.4 mode (MLC is still possible)
  • -nopml -- Disables PML multiplexing
  • -devidset string -- Overrides entire device ID string (not recommended)
• Valid options for par:
  • -base 0xADDR -- I/O port base address (default is 0x378)
  • -basehigh 0xADDR -- ECP high base address (default is base+0x400)
  • -device /dev/lp0 -- Path and filename of corresponding device node, used to lock the port and prevent interference from other processes
  • -porttype porttype -- Overrides port-type detection, one of:
    • spp -- Standard (unidirectional) parallel port
    • bpp -- Bidirectional (PS/2, not ECP) parallel port
    • ecp -- Extended Capabilities Port with no hardware assistance
    • ecphw -- Currently the same as ecp
• Valid options for usb:
  • -device /dev/usb/lp0... -- Path and filename of device node (required, multiple device nodes and/or wildcards are OK)
  • -devidmatch string -- Matches portion of device ID string, useful for usb if multiple -device nodes are specified

General notes

A ptal-mlcd process exists in one of several overall states. When startup is complete, it is in the inactive state. When an application tries to access the peripheral, ptal-mlcd starts to activate, or in other words, establish an MLC/1284.4 communication session with the peripheral. Once that is complete, ptal-mlcd is in the active state. If a communication error happens, which could be the result of a power-off or disconnection of the peripheral or a protocol error, ptal-mlcd deactivates, which includes closing all active application sessions and returning to the inactive state.

ptal-mlcd special-cases the PML (Peripheral Management Language) service on the peripheral, by keeping open a single PML channel while activated, virtualizing application requests to open the PML service, and multiplexing PML requests (gets and sets but not yet traps) from possibly multiple applications over a single PML session with the peripheral. On the other hand, if you specify the -nopml switch, then this behavior is disabled, and only one application may open PML at a time but it has exclusive access to the peripheral's PML service.

Parallel-specific notes

	ptal-mlcd par:0 [-base 0xADDR] [-basehigh 0xADDR] \
		-device /dev/lp0 [-remconsole]

USB-specific notes

	ptal-mlcd usb:OfficeJet_G85 -device /dev/usb/lp* \
		-devidmatch "MDL:OfficeJet G85;" [-remconsole]

Alternatively, if you only have one USB-connected printer device, you can use a simpler command line such as the following:

	ptal-mlcd usb:0 -device /dev/usb/lp0 [-remconsole]

The -hotplug switch is provided if you want to load ptal-mlcd from a hotplug script. It causes ptal-mlcd to attempt to activate right away and exit if it ever loses and fails to re-establish communication with the peripheral, which would normally only happen due to an unplug or power-off event. However, this usage is not recommended under Linux, because the information on which printer device node corresponds to the hotplugged device is not available to user-mode tools such as ptal-mlcd.

User interface

• Special "virtual" services
• Log messages to standard output and syslog (/var/log/messsages)
• A debug console

• PTAL-MLCD-CONSOLE -- The debug console, if enabled with the -remconsole switch
• PTAL-MLCD-PID -- The process ID of this instance of ptal-mlcd
• PTAL-MLCD-CMDLINE -- The command line passed to this instance of ptal-mlcd
• PTAL-MLCD-DEVNODE -- The device node, if any, in use by this instance of ptal-mlcd
• PTAL-MLCD-DUMP -- A dump of the current state of most internal data structures (useful for debugging)

• FATAL ERROR -- An internal error bad enough to cause ptal-mlcd to exit. Normal behavior if a startup error (such as command-line syntax error or problem setting up socket) occurred or due to an exit requested by the -hotplug switch. Otherwise, should never happen. If it does, especially if it's preceeded by a large data-structure dump, then please report the problem to the hpoj-devel mailing list.
• ERROR -- An error, such as a loss of communication with the peripheral, which is (hopefully) recoverable without exiting. Probably not a bug, with the exception of an fdRegister error, which should be reported to the hpoj-devel mailing list.
• WARNING -- An unusual situation that could potentially indicate a problem, but which is (hopefully) immediately recoverable with no adverse effect.
• SYSLOG -- An information message by default logged only to syslog, not standard output, indicating successful startup or activation.
• ENTRY, EXIT, INFO -- Debug messages.

	ptal-mlcd: ERROR at ExMgr.cpp:849, dev=<par:0>, pid=1010, errno=11
	exClose(reason=0x000F)

• ERROR indicates the severity (see above for the possibilities).
• ExMgr.cpp:849 indicates the source-code file and line number where the message was logged. Useful for debugging.
• dev=<par:0> indicates the device name controlled by the ptal-mlcd instance that logged the message.
• pid=1010 indicates the process ID that logged the message.
• errno=11 indicates the current value of the errno variable, probably irrelevant unless it's an error message complaining about a failed system call.
• exClose(reason=0x000F) is the specific message with parameter substitution as appropriate. Some log messages, especially some fatal errors that should never happen (but occasionally they do:-) don't even have a customized second-line message.

• Invoke ptal-mlcd with the -remconsole switch, to enable the "remote" console capability. Issue a command such as:

  	ptal-connect mlc:usb:OfficeJet_G85 -service PTAL-MLCD-CONSOLE
  

  This will "steal" the console away from standard output or from another connection to this same service. Press Control-C or Control-D to exit ptal-connect and return the console back to standard output (and no standard input).
• Invoke ptal-mlcd with the -nofork switch, to prevent ptal-mlcd from forking itself into the background and start up the "local" console. Press Control-C to kill ptal-mlcd and return to the command prompt.

• dump -- Dumps all data structures.
• pid -- Prints the current process ID.
• activate -- Starts activation if not active. Prints return code of exActivate(), which may be 0 if already active, 1 if started (and probably finished) activating, and -1 if an error occurred.
• deactivate -- Deactivates by calling exClose(), which always logs an error message.
• log -- Enables all log messages, including debug messages.
• logwarn -- Enables log messages other than debug messages (ENTRY, EXIT, and INFO).
• nolog -- Returns to the default log level of logging ERROR and "FATAL ERROR" to standard output and syslog and SYSLOG to syslog but not standard output.

File-system usage

When libptal first opens the Unix-domain socket, it exchanges several request/reply packets with ptal-mlcd, which might include getting the device ID string, service name to socket ID lookup, socket ID to service name ("reverse") lookup, and channel open. In most cases, ptal-mlcd attempts to activate if it's not already active before processing one of these requests. After a successful open reply, for all practical purposes the connection is then a pass-through connection to the requested service on the peripheral.

ptal-mlcd maintains a fixed-maximum-size table of various kinds of "session" structures. Whenever a new connection is received from the named socket, it is assigned to a "command session", which handles the request/reply command interaction with libptal. When an open request is received, the command session is linked with either a "transport session" or virtual "PML session", depending on whether the open request was for a peripheral socket corresponding to the PML service (which is virtualized) or for a different service. As the open is processed the linked sessions go through several state transitions together. If/when the open succeeds, the connection is fully transferred from the command session to the transport or PML session, but if the open fails then the linked session is freed and the connection stays with the command session ready for possibly other commands.

ptal-mlcd depends on the /dev/null "bit-bucket" device for several purposes. First of all, it substitutes /dev/null for the standard input, output, and/or error file descriptors if they aren't already open, which is the case when invoked from a hotplug script. Second, it substitutes /dev/null file descriptors for sessions which don't have an associated file descriptor (such as the master PML session) or sessions which have been closed by libptal but are not ready to be completely torn down by ptal-mlcd (such as when ptal-mlcd gets an error writing to a session's file descriptor, which is not the right state for tearing down the session). The basic requirements for the /dev/null device are that select() should indicate ready to read and write, read() should return an end-of-file condition (zero bytes read), and write() should always "succeed" in writing all of the requested bytes.

Class hierarchy

• ParPort -- Handles access to parallel ports with PC-style register sets:
  • port type detection
  • timeouts
  • generic register access
  • IEEE 1284-1994 signalling:
    • negotiation into ECP and nibble modes
    • termination back to compatibility mode
    • ECP forward-to-reverse and reverse-to-forward
    • ECP forward data transfers
    • ECP and nibble reverse data transfers
  • Reading the device ID string
• IoParPort -- ParPort-derived class that defines specific mechanism of gaining access to and reading/writing the parallel-port registers, by using the x86/Alpha I/O port read/write instructions.

• QueueEntry, Queue -- Node and container base classes for a doubly-linked list (derived by message, watchdog timer, "BDR", and lookup classes).
• ExMsgHandler -- Base class for ExMgr, ExTransport, and ExTransportChannel classes that serves as a template for receiving messages (either dispatched explicitly or as a result of a watchdog timer).
• ExMsg -- Contains destination and parameter information to route a message to the correct ExMsgHandler-derived class.
• ExMsgQueue -- Used to store free (available) or pending messages.
• PolledTimer -- After being "started" with a particular timeout or delay, is polled periodically to determine if the timeout has passed. Also contains utility functions to delay a particular amount of time by blocking without polling.
• ExWatchdogTimer -- Once set with a timeout and started, "pops" if the timeout happens before being cancelled. This class takes two different forms, which determine the meaning of "pop":
  • A message-based timer has an ExMsg and an ExMsgHandler destination set. When the timer pops, the message is sent to the destination. Ordered in the ExWatchdogTimerQueue based on time remaining until pop.
  • A periodic timer has no ExMsg or ExMsgHandler set and is used only by various modules to request a maximum select() timeout. Ordered in the ExWatchdogTimerQueue based on timeout.
• ExCountingWatchdogTimer -- ExWatchdogTimer-derived class that starts the underlying timer every time a start request is received, and doesn't stop it until the same number of stop requests have been received.
• ExWatchdogTimerQueue -- Queues ExWatchdogTimer objects in the order they will pop.
• ExBdr -- "Buffer Data Record" -- Contains data buffer, offset, length, and owning transport channel (if any). BDRs for a single packet (i.e. header and multiple data BDRs) may be chained together to ensure uninterrupted transmission. Note that this is not the same as several BDRs stored in a queue, although in some situations the chain is broken up and each BDR queued separately.
• ExBdrQueue -- Stores BDRs containing data waiting to be processed (except when used by an ExBufferPool).
• ExBufferPool -- Stores free (available) BDRs. Uses a "lazy allocation" algorithm, in that BDRs aren't allocated until they're needed, to reduce memory consumption in the average case.
• ExSessionLookup -- ExLookup-derived class that stores an scd attribute missing from the ExLookup class (see below).
• ExMgr -- Base class for ParMgr and UsbMgr that manages lots of things:
  • buffer pool
  • transport (see below)
  • main runtime loop (exMain()) that revolves around select()
  • file descriptor sets for select() (from console, socket, sessions, and LLIO)
  • command-line processing
  • /dev/null
  • message queue and pool
  • timer queues
  • debug console
  • named Unix-domain socket
  • application sessions (command, transport, and virtual PML)
  • low-level I/O ("LLIO"), partially implemented in derived classes
• ParMgr -- ExMgr-derived class for parallel-port connections to glue ParPort functionality into ExMgr.
• UsbMgr --ExMgr-derived class for USB connections to implement device ID retrieval.

• ExLookup, ExLookupQueue -- Stores parameters/results of requests for 1284.4 service name to socket ID (and vice versa) lookup.
• ExCounter -- Maintains a counter up to MAXINT (-1, to prevent wraparound).
• ExDebugCounter -- ExCounter-derived class that only increments for debug purposes, and otherwise just does a plain set.
• ExCreditCounter -- Maintains "credit" count for MLC/1284.4 and maximum outstanding forward packets.
• ExTransportChannel -- Handles the basic logic of forward and reverse data flow and reverse buffer management for a single data channel between the host and peripheral. Base class for ExMlcTransportChannel, not instantiated directly in ptal-mlcd.
• ExTransport -- Pass-through (raw) transport, manages a list of ExTransportChannel-derived objects, and provides non-channel-specific transport-level functionality.
• ExMlcCreditCounter -- ExCreditCounter-derived class that sets the maximum credit count of 0xFFFF.
• ExMlcTransportChannel -- ExTransportChannel-derived class that handles the specifics of an MLC/1284.4 channel, including channel open/close, forward/reverse data flow, and credit management.
• ExMlcCommandChannel -- ExMlcTransportChannel-derived class that handles sending/receiving of MLC/1284.4 command packets and special credit management needed for the command channel.
• ExMlcTransport -- ExTransport-derived class that manages the channel list consisting of one ExMlcCommandChannel object and many ExMlcTransportChannel objects, MLC/1284.4 packet header overhead, routing reverse data to the correct channel, negotiating the protocol revision (MLC or 1284.4), and service name lookup.

Porting considerations

• "Standard" Unix/Linux libc API and system-call semantics (whatever that means:-). It works on Linux, so from this standpoint it shouldn't be too hard to port it to other similar operating systems.
• The ParPort class assumes a PC-style parallel-port register set (with several annoying inverted bits in the control and status registers). The IoParPort class assumes that it can use x86/Alpha inb and outb operations to access these registers, and that it can give itself permission to do this in some OS-dependent manner. For porting purposes, IoParPort could be modified to support these operations on a different OS, or a different class could be derived from ParPort. Alternatively, the parallel-port support can be turned off entirely with the "./configure --without-par" switch.
• USB support depends on a (presumably kernel-mode) printer-class device driver which binds to the "7/1/3" USB interface on the peripheral, which is for MLC or 1284.4 packetized communication, not raw print data as is the case with 7/1/1 and 7/1/2. Bidirectional support is required. Also, there needs to be some sort of ioctl() call to retrieve the device ID string of the currently-attached peripheral, although it's OK if it's retrieved once on plug-in and cached for subsequent queries. A read() error needs to be returned when the device is unplugged or powered off.