Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials

Chapter 8 - Ports

About Ports

Central to Open Transport's architecture is the concept of a port. In Open Transport, a port is a logical entity that combines a hardware device and the software driver that acts as an interface to it. Ethernet, serial devices, and LocalTalk ports are examples of ports commonly used in Open Transport. When you initialize Open Transport, it scans the local machine for all available ports and creates a data structure called a port registry in which it stores information about these ports.

Typically, your application uses whichever port is defined in the appropriate control panel (for example, AppleTalk or TCP/IP). If, however, your application provides special port manipulation features, you need the additional port information data structures, constants, and functions that Open Transport provides for browsing among the ports available to your computer and for finding specific ports.

Identifying Ports

Open Transport provides a standard naming scheme for describing the ports available to a computer. There are two ways to identify each port uniquely: its port name and its port reference.

Port Name

The port name is a unique name that designates the port. This name identifies the port without using any location information. For instance, "ltlkA" identifies LocalTalk on the serial port, and "ltlkB" identifies LocalTalk on the modem port. This name must always be used in the path string for the OTCreateConfiguration function to uniquely identify a port.

The port name is typically an abbreviation of the port's device type plus a suffix, usually numeric, such as "enet0," "enet1," and "enet2." For historic reasons, LocalTalk and serial ports use an alphabetic suffix instead. For example, "ltlkA" is the modem port and "ltlkB" is the printer port. The port name is a zero-terminated string that can have a maximum length of 36 bytes: 31 bytes for the name, up to 4 bytes of extra characters (called minor numbers in XTI specifications) that are currently not used, and a byte for the terminating zero.

You can identify a port using only the device name, in which case Open Transport uses the first device of that type that has been registered and is available. For most devices this means the built-in device, if one exists. Otherwise, this refers to the first slotted device that has been registered.

Port Reference

You can also uniquely identify a port with a port reference, which is a 32-bit value that describes a port's hardware characteristics: its device and bus type, its physical slot number, and, where applicable, its multiport identifier. For details of the possible values you can use in a port reference, see "The Port Reference".

Multiport Identifiers

The multiport identifier is a port function parameter that distinguishes between multiple ports when a single slot supports more than one port of the same device type. This parameter, called other, is part of the port reference structure, which is described in "The Port Reference".

Typically, the hardware device in a multiport slot is either a plug-in multifunction card with multiple ports on it or a device with multiple uses, one or more of which is a port. An example of a multifunction card is the SerialNB card with its four ports; an example of a multi-use device on most Macintosh computers is the SCC chip that can handle both LocalTalk and serial communications. Typically, a multifunction card has multiple ports that use different values for the other parameter and possibly different device attributes. A multi-use device is registered with all attributes identical except for the device type.

Pseudodevices

There's a special type of port, called a pseudodevice, that is a driver that doesn't interface to a hardware device; instead, it interfaces to other device drivers. Pseudodevices are provided as a convenience for the Open Transport architecture. Open Transport defines special device types for certain common pseudodevices, such as modem, PPP, and SLIP. Because Open Transport can't possibly accommodate all possible pseudodevices, there is a generic device type, designated with the constant kOTPseudoDevice, that identifies unknown or unusual pseudodevices. Each pseudodevice must have a unique port reference. Typically, a pseudodevice is private, and a flag indicating that the port is private notifies applications browsing the port registry that the port is not normally available for public use.

Port Structures

Every port on the computer is described in Open Transport by a port structure, which contains its port reference, several sets of information flags, its port name, its STREAMS module name, and the slot ID (for ports on a PCI bus). For details of the port structure, see "The Port Structure".

The port structure includes fields that allow you to identify a port's child port, which allows you to identify which of several available hardware devices the port uses. A port may have more than one child port, all of which can be active simultaneously.

For example, in many implementations, a SLIP port is a pseudodevice that uses a serial port as its hardware device. If more than one serial port is available, the SLIP pseudodevice could use any of them. A SLIP port therefore always has a serial port as its child port so that when multiple serial ports are available, you can use the child port information to find out which serial port the SLIP port is using. Other device types, such as Ethernet devices, do not have child ports because they have a one-to-one relationship with their hardware device--that is, they have only one possible choice for the hardware device they can use.

The slot ID is a user-visible identifier used for cards on PCI bus computers. To derive this value, Open Transport accesses information in the Name Registery, which is a register of hardware and software configuration information for Power Macintosh computers that is maintained by Mac OS. For more information about the Name Registry, see Designing PCI Cards and Drivers for Power Macintosh Computers.

One set of flags indicate a port's framing capabilities--that is, the different packet headers and trailers (data frames) permitted by the protocol on that port. The framing flags are specific to the device type being registered. See the appropriate documentation for the device to determine how to interpret these flags.

For each hardware device type, Open Transport derives a default port name based on the port name by stripping its numeric (or alphabetic, in the case of LocalTalk and serial ports) suffix. All ports on a computer that are the same hardware device type result in the same default port name. Thus, Ethernet devices default to "enet." For all hardware device types, you can use the default port name as part of the configuration string. If you use a default name such as "enet," Open Transport uses whichever port is identified as the default port. If it can't find that port, OpenTransport returns an error message.

In the case of LocalTalk, however, Open Transport uses a flag to define a specific port as a port alias, or a default port, for LocalTalk ports. This port is called "ltlk" and uses the same Streams module name as the default LocalTalk port. Normally, the LocalTalk default port is the printer port, "ltlkB," but if a computer doesn't have an "ltlkB" port, then the LocalTalk default is the modem port, "ltlkA". Because both the port alias and the default port have the same STREAMS module name, when you use the port alias to configure the port, Open Transport can locate the default port even if a port doesn't use the standard "ItlkB" default.

---

Subtopics

Identifying Ports

Port Name

Port Reference

Multiport Identifiers

Pseudodevices

Port Structures