sceNetAdhocMatching

The matching library is a ready-made lobby protocol on top of PDP. A host advertises itself, clients see the advertisement, ask to join, and are accepted or rejected; the library then keeps the member list alive and can send data to members. Plenty of games use it (PPSSPP's code mentions Patapon 3, Gran Turismo, Dissidia 012 and GTA: Vice City Stories, among others); others build their own lobby over PDP broadcasts.

API

Modes

Functions

The callback is callback(int id, int event, u8 *mac, int optlen, void *opt):

A typical session

  host                                 client
  Create(HOST) + Start(hello data)     Create(CLIENT) + Start
  ---- HELLO (broadcast, every hello_int) ---->   event HELLO
                                       SelectTarget(host)
  event REQUEST  <---- join request ----------
  SelectTarget(client)
  ---- accept ------------------------------->   event ACCEPT
  event ESTABLISHED                              event ESTABLISHED
  <---- keep-alive, both ways, every keepalive_int ---->
  SendData / event DATA, both ways

What two PSPs actually do (the net/adhoc/pair/matching test, with the client cancelling at the end):

• A second SelectTarget for the same peer gives REQUEST_IN_PROGRESS, on both sides.
• A second SendData before the first is acknowledged gives DATA_BUSY.
• GetMembers lists the console itself first, then the other, on both sides; after the cancel, each lists only itself.

Error codes

Sony's protocol

The firmware's matching module sends these packets over PDP on the context's port. This layout comes from the module's code; nobody has captured it on the air. The tests confirm what follows from it at the API level: the timeout of about keepalive_int * init_count, a full host no longer advertising, and data acks that come from the peer. Every packet starts with a 4-byte header, and all integers are big-endian:

Argument checks

Confirmed with the net/adhoc/matching test in pspautotests:

• Create:
  • Mode 1-3 (INVALID_MODE) and maxnum 2-16 (INVALID_MAXNUM), in every mode.
  • rxbuflen at least 6 * maxnum + 4 (RXBUF_TOO_SHORT): 28 for a maxnum of 4, 16 for 2.
  • In HOST and P2P mode, non-zero hello_int and keepalive_int; a client may pass 0 for both.
  • init_count not negative, rexmt_int non-zero (INVALID_ARG).
  • Port 0, an init_count of 0 and a NULL handler are accepted. No defaults are filled in.
  • Two contexts on one port give PORT_IN_USE.
  • Before Init it gives NOT_INITIALIZED.
• Init twice gives ALREADY_INITIALIZED; Term returns 0 even when not initialized.
• Not started: SelectTarget, CancelTarget, SendData, SetHelloOpt, GetHelloOpt and GetMembers give NOT_RUNNING; Stop returns 0.
• Started: Start again and Delete both give IS_RUNNING; the context must be stopped first. Targets that aren't peers give UNKNOWN_TARGET.
• GetHelloOpt copies at most the buffer size the game passes in optlen, and leaves optlen as it was.
• GetMembers on a host with nobody else around reports one member (12 bytes): itself.
• An unknown context ID gives INVALID_ID.

Timers

• Each established peer has a counter, reset to init_count whenever anything arrives from it and decremented every keepalive_int. When it reaches 0 the peer is sent a cancel and the game gets TIMEOUT. So a peer times out after about keepalive_int * init_count of silence.
• Join requests and accepts are resent every rexmt_int, up to init_count times, then time out.
• Data is resent every rexmt_int until acknowledged, up to init_count times, then DATA_TIMEOUT.

The aemu protocol (what PPSSPP sends)

PPSSPP implements the matching library itself (the firmware module is never loaded), using the packet format of the aemu plugin. This is a different protocol from Sony's, so PPSSPP's matching works with other PPSSPPs and with PSPs running aemu, but not with the real module. The event numbers the game sees are the same.

Packets are an opcode byte followed by little-endian 32-bit lengths, unaligned:

Differences from Sony's protocol:

• No version byte, no length header, no session IDs or sequence numbers.
• Keep-alive is a 1-byte PING, not the member list. The member list is sent once in the ACCEPT, then maintained with BIRTH and DEATH.
• Nothing is retransmitted. JOIN and ACCEPT are sent once, data isn't acknowledged by the peer: DATA_ACK is generated locally right after SendData, and DATA_TIMEOUT never happens.
• HELLO and PING go to every peer in the adhocctl peer list, as individual datagrams, rather than as one broadcast.

How PPSSPP implements it

Games named in this section are the ones PPSSPP's code gives as the reason for a behaviour. That those games need it hasn't been rechecked.

Threads

  game thread            host thread             host thread             PSP thread
  SelectTarget etc. ---> MatchingInput           MatchingEvent           MatchingThr<id>
  (pushes messages)      sends HELLO/PING,       every 10 ms, moves      loops: take one event,
                         sends queued packets,   events to the global    call the game's callback,
                         receives and handles    callback queue          sleep 3 ms
                         packets, timeouts

• MatchingInput (a host thread per context) sends HELLO every hello_int (host with room, or P2P without a partner) and PING every keepalive_int, checks timeouts, sends the packets queued by the HLE functions, and reads and handles incoming packets. It loops every 10 ms.
• MatchingEvent (a host thread per context) moves the events produced by MatchingInput into a global queue, every 10 ms, with the opt data copied into PSP memory.
• MatchingThr<id> (a PSP thread per context, created by Start with the game's event thread priority and stack size) takes one event at a time and calls the game's callback with it, then sleeps 3 ms. Callbacks are never run concurrently. The 3 ms spacing was tuned: Super Pocket Tennis and Thrillville need about 5 ms or less, Gundam: Senjou no Kizuna Portable with 4 players needs about 3 ms.
• SendData sends directly from the calling thread.

The PDP socket is created by Start, not Create; creating it earlier left Dissidia 012 unable to see any rooms. In relay mode, it's a reliable relay socket.

Peer states

Timeouts

A peer times out when nothing has been heard from it for (keepalive_int + rexmt_int) * init_count + 500 ms, with the extra 500 ms for internet latency. Only PING (and the peer's creation) counts as hearing from it in matching. GetMembers additionally refreshes each member's timer from the adhocctl peer list, so a member that is still sending other traffic doesn't time out while the game keeps polling it.

A keepalive_int below 1 is replaced with 2 seconds. (On the PSP it's an error in HOST and P2P mode.)

Member order

GetMembers returns the host first, then the children in the order they joined, matching the host's own view. Gran Turismo and Patapon 3 rely on all members agreeing on the order.

Other game-driven behaviour

• Start on an unknown ID returns 0 (GTA: Vice City Stories).
• CancelTarget on a peer in a state that can't be cancelled returns 0 (Soul Calibur).
• A client ignores HELLOs from a host while a join is in progress (Super Pocket Tennis).
• In P2P mode, a rejected request leaves the peer in the list so it times out normally (Crazy Taxi).
• Stop sends BYE to all members. (The firmware may send DEATH-like packets instead, but that breaks Dragon Ball Z Tag Team.)
• GetMembers counts one extra member in client mode (Ys vs. Sora no Kiseki).

Savestates

Matching contexts aren't saved. A savestate taken during matching loads with no contexts, and the game's next matching call on its old ID fails. Only the library's initialized flag and its thread IDs are saved.